fabric CartPayments API

openapi: 3.2.0
info:
  title: Cart Orchestrator Cart Payments API
  description: API for managing shopping carts
  version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
  description: Production server
- url: https://stg.api.fabric.inc/v3
  description: Staging server
security:
- bearerAuth: []
tags:
- name: CartPayments
  description: CartPayments endpoints are used to authorize or void payments that are located within the shopping cart.
paths:
  /orchestrator/carts/{cartId}/payments/actions/authorize:
    post:
      summary: Authorize Payments
      description: 'Authorize payments made within the corresponding cart.


        The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.

        '
      operationId: authorizePayment
      tags:
      - CartPayments
      parameters:
      - $ref: '#/components/parameters/XFabricTenantId'
      - $ref: '#/components/parameters/XFabricRequestId'
      - $ref: '#/components/parameters/XFabricChannelId'
      - name: cartId
        in: path
        required: true
        schema:
          type: string
        description: The 24-character system-generated Cart ID. This ID is generated using the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint.
      responses:
        '200':
          description: Payments authorized successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unprocessable Orchestration Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableOrchestrationError'
  /orchestrator/carts/{cartId}/payments/actions/void:
    post:
      summary: Void Payments
      description: 'Void payments made within the corresponding cart.


        The Cart ID from the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.

        '
      operationId: voidPayment
      tags:
      - CartPayments
      parameters:
      - $ref: '#/components/parameters/XFabricTenantId'
      - $ref: '#/components/parameters/XFabricRequestId'
      - $ref: '#/components/parameters/XFabricChannelId'
      - name: cartId
        in: path
        required: true
        schema:
          type: string
        description: The 24-character system-generated Cart ID. This ID is generated using the [Create cart](/v3/api-reference/carts-v3/carts/carts) endpoint.
      responses:
        '200':
          description: Payments void successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          description: Unprocessable Orchestration Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableOrchestrationError'
components:
  schemas:
    PaymentCollection:
      type: object
      properties:
        authorized:
          type: number
          description: The payments that have been authorized within the collection.
          example: 800
        collection:
          type: array
          description: An array containing payments within the collection.
          items:
            $ref: '#/components/schemas/Payment'
      description: An object containing a collection of payments added to the cart.
    ItemResponseDto:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the item.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        sku:
          type: string
          description: The Stock Keeping Unit (SKU) associated with the item, used for inventory tracking and management.
          example: SKU3
        refId:
          type: string
          description: An alternative identifier associated with the item, used for additional tracking or referencing.
          example: '41'
        quantity:
          type: integer
          description: An integer that displays the total quantity of the item.
          format: int32
          example: 10
        priceListId:
          type: string
          description: The unique identifier for a price list, used to reference and manage pricing information.
          example: '10001'
        position:
          type: integer
          description: Position of item in a cart.
          format: int32
          example: 1
        price:
          $ref: '#/components/schemas/ItemPrice'
        fees:
          $ref: '#/components/schemas/FeesCollection'
        promotions:
          $ref: '#/components/schemas/ItemPromotionsCollection'
        adjustments:
          $ref: '#/components/schemas/AdjustmentCollection'
        fulfillment:
          $ref: '#/components/schemas/ItemFulfillment'
        attributes:
          type: object
          additionalProperties:
            type: object
            description: Custom attributes to provide more context for the item.
            example:
              name: item-custom
          description: Custom attributes to provide more context for the item.
          example:
            name: item-custom
        tax:
          $ref: '#/components/schemas/TaxCollection'
        taxCode:
          type: string
          description: The code used to identify and apply tax rates for transactions.
          example: '10001'
        updatedAt:
          type: string
          description: The date and time in UTC when the cart was last updated.
          example: 2024-06-13 16:50:00.682000+00:00
        createdAt:
          type: string
          description: The date and time in UTC when the cart was last updated.
          example: 2024-06-13 16:50:00.682000+00:00
      description: Item Response
    Name:
      type: object
      properties:
        first:
          type: string
          description: First name
          example: John
        last:
          type: string
          description: Last name
          example: Doe
    TaxValidationData:
      type: object
      properties:
        updatedAt:
          type: string
          description: Latest date the tax was added to the cart.
          example: 2024-06-13 16:50:00.682000+00:00
      description: Tax validation data
    ProductConfiguration:
      type: object
      properties:
        cacheExpiry:
          type: integer
          description: Duration in seconds until product validation data expires.
          format: int64
          example: 7776000
        behaviors:
          $ref: '#/components/schemas/ProductBehaviour'
        maxQuantity:
          $ref: '#/components/schemas/MaxQtyConfiguration'
      description: Configuration settings related to product behavior and cache expiry.
    Promotion:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the promotion.
          example: 6626c179627d450008a5b202
        title:
          type: string
          description: Promotion title
          example: Cart Promotion Fixed Price
        type:
          type: string
          description: The type of promotion, such as percentage or fixed value.
          example: QUANTITY
        value:
          type: number
          format: float
          description: The value of the promotion, indicating the amount of the discount applied. This can be a fixed amount or a percentage.
          example: 10
        attributes:
          type: object
          additionalProperties:
            type: string
          description: Custom attributes provide more context for the promotion.
          example:
            promotionStack: HIGHEST
    InventoryConfiguration:
      type: object
      properties:
        cacheExpiry:
          type: integer
          description: Duration in seconds until inventory validation data expires.
          format: int64
          example: 7776000
        behaviors:
          $ref: '#/components/schemas/InventoryBehaviour'
        check:
          type: string
          description: This setting is used to determine how you check inventory. The options are SKU or LINE_ITEM.
          example: SKU
          enum:
          - SKU
          - LINE_ITEM
      description: Configuration settings related to inventory management and checks.
    MaxQtyConfiguration:
      type: object
      properties:
        limit:
          type: integer
          description: The maximum quantity of an individual line item that can be added to the cart.
          format: int32
          example: 100
        behaviors:
          $ref: '#/components/schemas/MaxQtyBehaviour'
      description: Item max quantity configurations
    PaymentAuthorization:
      required:
      - amount
      type: object
      properties:
        amount:
          type: number
          description: The amount for which the payment has been authorized.
          example: 8
          exclusiveMinimum: 0
        expiry:
          type: string
          description: The date when the payment authorization expires.
          example: 2024-06-13 16:50:00.682000+00:00
        verifier:
          $ref: '#/components/schemas/Verifier'
      description: Payment authorization
    SKUValidationData:
      type: object
      properties:
        sku:
          type: string
          description: The SKU that exists within a Product Information Management (PIM) service.
          example: SKU3
        updatedAt:
          type: string
          description: The latest date when product data was added to the cart.
          example: 2024-06-13 16:50:00.682000+00:00
        maxQuantity:
          type: integer
          description: The maximum quantity allowed for a SKU.
          format: int32
          example: 100
      description: Product validation data to determine product existence
    PriceDetail:
      type: object
      properties:
        total:
          type: number
          format: float
          description: The grand total, inclusive of all charges and discounts.
          example: 1570
        subtotal:
          type: number
          format: float
          description: The subtotal of all items.
          example: 1530
        tax:
          type: number
          format: float
          description: The total tax calculated amount.
          example: 0
        fulfillments:
          type: number
          format: float
          description: The total fulfillments amount.
          example: 40
        discounts:
          type: number
          format: float
          description: The total discounts amount.
          example: 0
        fees:
          type: number
          format: float
          description: The total fees amount.
          example: 0
        adjustments:
          type: number
          format: float
          description: The total adjustments amount.
          example: 0
      description: The sum of the total amount of the cart.
    Phone:
      type: object
      properties:
        number:
          type: string
          description: Phone number
          example: '1234567890'
        type:
          type: string
          description: Type of phone number (e.g., MOBILE, HOME)
          example: MOBILE
    ItemPromotion:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the promotion.
          example: bb44db95-6fbd-4eed-a1ed-4d99bc91250f
        amount:
          type: number
          description: The discount amount applied to the item, excluding quantity.
          example: 15
        quantity:
          type: integer
          description: The An integer that displays the total quantity of the item. for which the discount is applicable.
          format: int32
          example: 3
        proration:
          $ref: '#/components/schemas/ProrationSpread'
      description: Item Promotion
    Proration:
      type: object
      properties:
        amount:
          type: number
          description: Proration amount for the item
          example: 5
        quantity:
          type: integer
          description: Proration quantity the amount is applicable for
          format: int32
          example: 3
      description: Proration details of the item used for returns in an OMS system
    ItemPromotionsCollection:
      type: object
      properties:
        total:
          type: number
          description: Discount total in the collection.
          example: 2
        collection:
          type: array
          description: An array containing promotions in the collection.
          items:
            $ref: '#/components/schemas/ItemPromotion'
      description: Collection of item promotions.
    InventoryBehaviour:
      type: object
      properties:
        add:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is REJECT.

            '
          example: REJECT
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
        update:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is WARN.

            '
          example: WARN
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
        get:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is WARN.

            '
          example: WARN
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
        cacheExpiry:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is WARN.

            '
          example: WARN
          enum:
          - WARN
          - DROP
          - REJECT
          - NONE
      description: Behaviors related to inventory actions, such as adding the item or removing the item.
    Error:
      type: object
      properties:
        code:
          type: string
          description: The error code as a result of the error.
          example: ERR001
        message:
          type: string
          description: The error message to provide more context for the error.
          example: Invalid input
      description: An object containing the error code and message.
    CartResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the cart that was passed in the parameter.
          example: 0e49199c-5849-4211-abe6-a97a3c4dcc56
        attributes:
          $ref: '#/components/schemas/Attributes'
        configuration:
          $ref: '#/components/schemas/CartConfiguration'
        customerContext:
          $ref: '#/components/schemas/CustomerContext'
        status:
          type: string
          description: The cart status indicates whether the cart is active or deleted.
          example: ACTIVE
          enum:
          - ACTIVE
          - SOFT_DELETE
        state:
          type: array
          description: The resource state is stored in an array that holds information about the current status of the cart.
          items:
            $ref: '#/components/schemas/State'
        price:
          $ref: '#/components/schemas/PriceDetail'
        promotions:
          $ref: '#/components/schemas/Promotions'
        fees:
          $ref: '#/components/schemas/Fee'
        adjustments:
          $ref: '#/components/schemas/AdjustmentCollection'
        addresses:
          type: object
          properties:
            a8577d7f0d4d4b228e857b4a2e90dc93:
              $ref: '#/components/schemas/Address'
          description: A map of addresses added to the cart.
        lineItems:
          $ref: '#/components/schemas/ItemCollection'
        summary:
          $ref: '#/components/schemas/Summary'
        fulfillments:
          type: object
          properties:
            d6229cdb0c5b4885b1b213b94d02488e:
              $ref: '#/components/schemas/Fulfillment'
          description: A map of fulfillments added to the cart.
        coupons:
          type: array
          description: An array containing all coupons added to the cart.
          items:
            $ref: '#/components/schemas/Coupon'
        appliedCoupons:
          type: array
          description: An array containing all coupons applied to the cart.
          items:
            $ref: '#/components/schemas/Coupon'
        notAppliedCoupons:
          type: array
          description: An array containing any coupons that were ineligible and not applied to the cart.
          items:
            $ref: '#/components/schemas/Coupon'
        validations:
          $ref: '#/components/schemas/ValidationData'
        payments:
          $ref: '#/components/schemas/PaymentCollection'
        channelId:
          type: string
          description: Channel ID
          example: '12'
        currency:
          type: string
          description: The currency that the cart will use when an order is created.
          example: USD
        updatedAt:
          type: string
          description: The date and time in UTC when the cart was last updated.
          example: 2024-06-13 16:50:00.682000+00:00
        createdAt:
          type: string
          description: The date and time when a cart was created.
          example: 2024-06-13 16:50:00.682000+00:00
        suggestedProducts:
          type: array
          items:
            $ref: '#/components/schemas/SuggestedProduct'
        promotionMessages:
          type: array
          items:
            $ref: '#/components/schemas/PromotionMessage'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Person:
      required:
      - name
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Name'
        email:
          type: string
          description: Email of the pickup person.
          example: john@test.com
        phone:
          $ref: '#/components/schemas/Phone'
      description: Name of the pickup person.
    ItemCollection:
      type: object
      properties:
        total:
          type: number
          description: Item total in a collection.
          example: 100
        collection:
          type: array
          description: An array containing items in the collection.
          items:
            $ref: '#/components/schemas/ItemResponseDto'
      description: A collection of items in the cart.
    LineItemValidationData:
      type: object
      properties:
        sku:
          type: string
          description: The SKU of the item.
          example: SKU3
        inventory:
          $ref: '#/components/schemas/InventoryValidationData'
      description: An object that contains item validation data.
    UnprocessableOrchestrationError:
      type: object
      properties:
        type:
          type: string
          example: UNPROCESSABLE_ORCHESTRATION
        message:
          type: string
          example: 4xx Error from orchestration dependency
        errors:
          type: array
          items:
            $ref: '#/components/schemas/OrchestrationError'
    CartConfiguration:
      type: object
      properties:
        order:
          $ref: '#/components/schemas/OrderConfiguration'
        product:
          $ref: '#/components/schemas/ProductConfiguration'
        inventory:
          $ref: '#/components/schemas/InventoryConfiguration'
        tax:
          $ref: '#/components/schemas/TaxConfiguration'
        promotions:
          $ref: '#/components/schemas/PromotionsConfiguration'
      description: Cart [configurations](/v3/api-reference/carts-v3/configuration-behaviors) determine the behavior within the cart.
    Promotions:
      type: object
      properties:
        total:
          type: number
          format: float
          description: The total value of all applied promotions.
          example: 0
        collection:
          type: array
          description: An array containing promotions in the collection.
          items:
            $ref: '#/components/schemas/Promotion'
      description: A collection of promotions applied to the cart.
    PickupPerson:
      type: object
      properties:
        primary:
          $ref: '#/components/schemas/Person'
        secondary:
          type: array
          description: An array containing secondary people for pickup.
          items:
            $ref: '#/components/schemas/Person'
      description: Pickup person details
    SuggestedProduct:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the suggested product.
          example: '12345'
        name:
          type: string
          description: The name of the suggested product.
          example: Wireless Mouse
        description:
          type: string
          description: The name of the suggested product.
          example: A high-quality wireless mouse with ergonomic design.
        price:
          type: number
          format: float
          description: The price of the suggested product.
          example: 29.99
    TaxBehaviour:
      type: object
      properties:
        cacheExpiry:
          type: string
          description: 'The behavior that is executed based on the selected configuration.


            The default behavior is WARN.

            '
          example: WARN
          enum:
          - WARN
          - NONE
      description: Tax behaviors
    PromotionsConfiguration:
      type: object
      description: Configuration settings related to promotions and their cache expiry.
      properties:
        cacheExpiry:
          type: integer
          example: 86400
        behaviors:
          $ref: '#/components/schemas/Behavior'
    Fulfillment:
      type: object
      properties:
        id:
          type: string
          description: The Fulfillment ID generated when a fulfillment was created using the [Create fulfillment](/v3/api-reference/carts-v3/fulfillment/create-fulfillments) endpoint.
          example: d6229cdb-0c5b-4885-b1b2-13b94d02488e
        type:
          type: string
          description: Determines the type of fulfillment.
          example: SHIP_TO
          enum:
          - SHIP_TO
          - BOPIS
          - ROPIS
        refId:
          type: string
          description: An alternative identifier for fulfillments, used for additional tracking or referencing.
          example: '398427903843'
        attributes:
          type: object
          description: Custom attributes to provide more context to the fulfillment, such as where it was made.
          additionalProperties:
            type: object
            description: Custom attributes to provide more context to the fulfillment, such as where it was made.
            example:
              source: store
          example:
            source: store
        originAddress:
          type: string
          description: The identifier of the address where the item is being fulfilled.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        destinationAddress:
          type: string
          description: The identifier of the address where the item is being shipped.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        locationId:
          type: string
          description: Unique identifier of the store.
          example: CA
        pickupPerson:
          $ref: '#/components/schemas/PickupPerson'
        price:
          $ref: '#/components/schemas/ResourcePrice'
        promotions:
          $ref: '#/components/schemas/FulfillmentPromotionCollection'
        fees:
          $ref: '#/components/schemas/FeesCollection'
        adjustments:
          $ref: '#/components/schemas/AdjustmentCollection'
        tax:
          $ref: '#/components/schemas/TaxCollection'
      description: A fulfillment object containing important fulfillment information.
    OrchestrationError:
      type: object
      properties:
        type:
          type: string
          example: NOT_FOUND
        message:
          type: string
          example: 404 Not Found from POST https://api.fabric.inc/carts/326949f9-7c25-4983-9848-b2061abb217dl/items/batch
        code:
          type: integer
          example: 404
        source:
          type: string
          example: POST https://api.fabric.inc/carts/326949f9-7c25-4983-9848-b2061abb217dl/items/batch
        details:
          $ref: '#/components/schemas/ErrorDetails'
    State:
      type: object
      properties:
        resource:
          type: string
          description: The type of resource indicating its current state, such as a cart.
          example: CART
          enum:
          - ITEM
          - CART
          - FULFILLMENT
          - PAYMENT
          - FEE
          - VALIDATION
        resourceId:
          type: string
          description: The ID used to reference the resource's state, such as a cart.
          example: c86f777b-1885-4ddf-961d-542ba80a69b8
        key:
          type: string
          description: The key used to map the state of the resource.
          example: MISSING_PAYMENT_DETAILS
        description:
          type: string
          description: A detailed description of the resource's current state, such as the absence of payment details.
          example: No payment details have been added to this Cart
      description: Cart State
    Verifier:
      type: object
      properties:
        type:
          type: string
          description: The type of verification used, such as a token.
          example: TOKEN
        key:
          type: string
          description: The key used for payment verification.
          example: CH39082K439R0
      description: Payment verifier
    Adjustment:
      type: object
      properties:
        id:
          type: string
          description: The Adjustment ID generated when an adjustment was created using the [Create adjustment](/v3/api-reference/carts-v3/carts-adjustments/create-adjustments) endpoint.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        price:
          $ref: '#/components/schemas/ResourcePrice'
        reason:
          type: string
          description: The reason for the adjustment.
          example: Price adjustment from customer representative.
        attributes:
          type: object
          additionalProperties:
            type: object
            description: Custom attributes used for price adjustments.
            example:
              source: CSR
          description: Custom attributes used for price adjustments.
          example:
            source: CSR
        updatedAt:
          type: string
          description: The date and time when the adjustment was last updated.
          example: 2024-06-13 16:50:00.682000+00:00
        createdAt:
          type: string
          description: The date and time when the adjustment was created.
          example: 2024-06-13 16:50:00.682000+00:00
      description: A collection of adjustments made to the cart.
    SegmentObject:
      type: object
      properties:
        name:
          type: string
          description: Segment name
          example: membership
        value:
          type: array
          description: Segment values
          example:
          - gold
          - silver
          items:
            type: string
            description: Segment values
            example: '["gold","silver"]'
    FeesCollection:
      type: object
      properties:
        total:
          type: number
          description: The total fees amount in the collection.
          example: 5
        collection:
          type: array
          description: An array containing all fees and their details in a collection.
          items:
            $ref: '#/components/schemas/Fee'
      description: A collection of fees associated with the cart.
    CustomerContext:
      type: object
      properties:
        id:
          type: string
          description: The Customer ID that was added to the customer attribute when using the [Update customer](/v3/api-reference/carts-v3/customer/update-customer) endpoint.
          example: '109840938'
        segments:
          type: array
          description: An array containing segments of customer information.
          items:
            $ref: '#/components/schemas/SegmentObject'
        attributes:
          type: object
          additionalProperties:
            type: object
            description: Customer attributes such as email.
            example:
              email: test@gmail.com
          description: Customer attributes such as email.
          example:
            email: test@gmail.com
        sessionId:
          type: string
          description: Session ID of the customer.
          example: 3a5fd2d3-5c96-4e57-b069-7ff2a88c1119
      description: Customer context object containing customer information.
    ErrorDetails:
      type: object
      properties:
        type:
          type: string
          example: CART_NOT_FOUND
        message:
          type: string
          example: Cart not found
        errors:
          type: array
          items:
            type: string
          example: []
    Summary:
      type: object
      properties:
        totalItems:
          type: integer
          description: The total number of items in the cart, inclusive of quantity.
          format: int32
          example: 1
        totalUniqueItems:
          type: integer
          description: The total number of unique items in the cart.
          format: int32
          example: 1
      description: A summary of items in the cart.
    TaxCollection:
      type: object
      properties:
        total:
          type: number
          description: Tax total in the collection.
          example: 3
        collection:
          type: array
          description: An array containing taxes in a collection.
          items:
            $ref: '#/components/schemas/Tax'
      description: A collection of taxes.
    Behavior:
      type: object
      description: Configuration for different behaviors in the system
      properties:
        add:
          $ref: '#/components/schemas/ConfigurationValue'
        update:
          $ref: '#/components/schemas/ConfigurationValue'
        get:
          $ref: '#/components/schemas/ConfigurationValue'
        cacheExpiry:
          $ref: '#/components/schemas/ConfigurationValue'
    Address:
      type: object
      properties:
        id:
          type: string
          description: The Address ID generated when an address was created using the [Create address](/v3/api-reference/carts-v3/addresses/create-addresses) endpoint.
          example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
        name:
          $ref: '#/components/schemas/Name'
        email:
          type: string
          description: Email
          example: john@test.com
        phone:
          $ref: '#/components/schemas/Phone'
        addressLine1:
          type: string
          description: Address line 1
          example: 123 Park Road
        addressLine2:
          type: string
          description: Address line 2
        addressLine3:
          type: string
          description: Address line 3
        addressLine4:
          type: string
          description: Address line 4
        city:
          type: string
          description: City
          example: Santa Cruz
        region:
          type: string
          description: State, Province or Area
          example: California
        country:
          type: string
          description: Country
          example: USA
        postalCode:
          type: string
          description: Postal code or zip code
          example: '12345'
        updatedAt:
          type: string
          description: The date and time the address was last updated.
          example: 2024-06-13 16:50:00.682000+00:00
        createdAt:
          type: string
          description: The date and time the address was created.
          example: 2024-06-13 16:50:00.682000+00:0

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-cartpayments-api-openapi.yml