fabric Invoices API

components:
  headers:
    xFabricRequestIdResponseHeader:
      description: Unique request ID
      example: 263e731c-45c8-11ed-b878-0242ac120002
      required: false
      schema:
        type: string
  parameters:
    xFabricChannelId:
      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.
      example: '12'
      in: header
      name: x-fabric-channel-id
      required: true
      schema:
        type: string
    xFabricChannelIdOptional:
      description: >-
        x-fabric-channel-id identifies the sales channel through which the API
        request is being made; primarily for multichannel use cases. It is an
        optional field. The default US channel is 12 while the default Canada
        channel is 13.
      example: '12'
      in: header
      name: x-fabric-channel-id
      required: false
      schema:
        type: string
    xFabricChannelIds:
      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. A comma separated list of
        sales channel IDs. This comma separated list of sales channel IDs are
        required when using multiple channels.
      example: 12, 13, 16
      in: header
      name: x-fabric-channel-ids
      required: false
      schema:
        type: string
    xFabricChannelIdsOptional:
      description: >-
        x-fabric-channel-id identifies the sales channel through which the API
        request is being made; primarily for multichannel use cases. It is an
        optional field. The default US channel is 12 while the default Canada
        channel is 13. This field is optional. **Note:** Use `xFabricChannelIds`
        for multiple channels, and `xFabricChannelId` for a single channel.
      example: 12, 13, 16
      in: header
      name: x-fabric-channel-ids
      required: false
      schema:
        type: string
    xFabricRequestId:
      description: Unique request ID
      example: 263e731c-45c8-11ed-b878-0242ac120002
      in: header
      name: x-fabric-request-id
      required: false
      schema:
        type: string
    xFabricTenantId:
      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.
      example: 5f328bf0b5f328bf0b5f328b
      in: header
      name: x-fabric-tenant-id
      required: true
      schema:
        type: string
  schemas:
    address:
      description: Address details
      properties:
        addressLine1:
          description: Address line 1
          example: 123 Main St.
          type: string
        addressLine2:
          description: Address line 2
          example: Suite 100
          type: string
        addressLine3:
          description: Address line 3
          example: Seventh floor
          type: string
        addressLine4:
          description: Address line 4
          example: 'Attention: Pat E. Kake'
          type: string
        city:
          description: City name
          example: Seattle
          type: string
        countryCode:
          description: ISO 3166-1 alpha-2 based country code
          example: US
          type: string
        email:
          description: Contact person's email
          example: [email protected]
          type: string
        latitude:
          description: >-
            Address latitude, used with `longitude` to specify the address
            location. Decimal degrees format; negative is degrees South.
            **Note:**Value must be between -90 and 90, both inclusive.
          example: 47.6205
          format: double
          type: number
        longitude:
          description: >-
            Address longitude, used with `latitude` to specify the address
            location. Decimal degrees format; negative is degrees South.
            **Note:**Value must be between -180 and 180, both inclusive.
          example: -122.3493
          format: double
          type: number
        name:
          $ref: '#/components/schemas/orderContactName'
        phone:
          $ref: '#/components/schemas/orderContactPhone'
        postalCode:
          description: Postal or ZIP code
          example: '98121'
          type: string
        region:
          description: Region or state
          example: WA
          type: string
        type:
          description: Address type
          example: Home
          type: string
      required:
        - addressLine1
        - city
        - countryCode
        - latitude
        - longitude
        - postalCode
        - region
        - type
      type: object
    addressWithContactsResource:
      description: Address with contact details
      properties:
        addressLine1:
          description: Address line 1
          example: 123 Main St.
          type: string
        addressLine2:
          description: Address line 2
          example: Suite 100
          type: string
        addressLine3:
          description: Address line 3
          example: Seventh floor
          type: string
        addressLine4:
          description: Address line 4
          example: 'Attention: Pat E. Kake'
          type: string
        city:
          description: City name
          example: Seattle
          type: string
        contacts:
          description: Contacts
          items:
            $ref: '#/components/schemas/invoiceContact'
          type: array
        countryCode:
          description: ISO 3166-1 alpha-2 based country code
          example: US
          type: string
        email:
          description: Contact person's email
          example: [email protected]
          type: string
        latitude:
          description: >-
            Address latitude, used with `longitude` to specify the address
            location. Decimal degrees format; negative is degrees South.
            **Note:**Value must be between -90 and 90, both inclusive.
          example: 47.6205
          format: double
          type: number
        longitude:
          description: >-
            Address longitude, used with `latitude` to specify the address
            location. Decimal degrees format; negative is degrees South.
            **Note:**Value must be between -180 and 180, both inclusive.
          example: -122.3493
          format: double
          type: number
        name:
          $ref: '#/components/schemas/orderContactName'
        phone:
          $ref: '#/components/schemas/orderContactPhone'
        postalCode:
          description: Postal or ZIP code
          example: '98121'
          type: string
        region:
          description: Region or state
          example: WA
          type: string
        type:
          description: Address type
          example: Home
          type: string
      required:
        - addressLine1
        - city
        - countryCode
        - latitude
        - longitude
        - postalCode
        - region
        - type
      type: object
    amountInCurrency:
      type: object
      description: Amount in currency  details
      properties:
        currency:
          type: string
          description: Currency in ISO-4217
          example: USD
        group:
          type: string
          description: Customer-defined function name which uses this currency.
          example: SHOPPER
        amount:
          type: number
          format: double
          description: Amount in currency
          example: 123.45
      required:
        - currency
        - group
    amountInCurrencyResource:
      type: object
      description: Amount in currency details
      properties:
        currency:
          type: string
          description: Currency in ISO-4217
          example: USD
        group:
          type: string
          description: Customer-defined function name which uses this currency.
          example: SHOPPER
        amount:
          type: number
          format: double
          description: Amount in currency
          example: 123.45
      required:
        - currency
        - group
    auditLog:
      description: Audit log to capture change history
      properties:
        amount:
          description: Amount for which audit's done
          example: 2.4
          format: double
          type: number
        auditId:
          description: System-generated audit ID (UUID format)
          example: a05b72dc-78d8-4ea4-90fc-2fe6a1fe1111
          type: string
        auditType:
          description: Audit type such as cancel, return, etc.
          example: CANCEL
          type: string
        auditedAt:
          description: Audit time (UTC)
          example: '2023-03-12T09:24:54.804Z'
          format: date-time
          type: string
        employeeId:
          description: Employee (ID or name) who made the last update
          example: '6227'
          type: string
        isSuccess:
          default: false
          description: >-
            true: Update operation (any update to the service) is successful 
            false: Update operation has failed
          example: true
          type: boolean
        lineItemId:
          description: >-
            Merchant-defined unique identifier for each item in an order. When
            omitted, fabric will generate it during order creation, in UUID
            format.
          example: b03b72dc-78d8-4ea4-90fc-2fe6a1fe6569
          type: string
        lineItemNumber:
          description: Item identifier
          example: 1
          format: int32
          type: integer
        note:
          description: Additional info, if any
          example: Note
          type: string
        paymentToken:
          $ref: '#/components/schemas/orderPaymentToken'
        policyCode:
          description: >-
            Configurable in Copilot as per requirement. If omitted, default
            policy is used.
          example: POS
          type: string
        quantity:
          description: Ordered quantity of given item
          example: 1
          format: int32
          type: integer
        reasonCode:
          description: Merchant-defined reason code, varies from merchant to merchant
          example: Scratched item
          type: string
        sku:
          description: Stock keeping unit (SKU), unique item identifier
          example: SKU0023
          type: string
        source:
          description: >-
            Merchant-defined source from where the update was initiated. There
            are no predefined values; possible values could be Customer Service
            Representative (CSR), Point-of-Sale (POS), etc.
          example: POS
          type: string
        subReasonCode:
          description: >-
            Merchant-defined sub reason code; provides more clarity to audit
            reason
          example: Scratched item
          type: string
        updatedFields:
          description: Audit log for change history
          items:
            $ref: '#/components/schemas/orderAuditLogUpdatedField'
          type: array
      type: object
    cancellationItemResource:
      type: object
      description: cancellation Item Resource
      properties:
        cancellationCounter:
          type: string
          description: Cancellation Counter
          example: 1
        source:
          type: string
          description: Determine where the request is initialized
          example: CSR
        reasonCode:
          type: string
          description: Reason code
          example: Order Line Cancel
        subReasonCode:
          type: string
          description: Sub reason code
          example: Late shipping
        status:
          type: string
          description: Cancellation Status
          enum:
            - PROCESSING
            - COMPLETED
            - REJECTED
          example: PROCESSING
        amount:
          type: number
          format: double
          description: Amount
          example: '-20.'
        amountInCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        invoicedAmount:
          type: number
          format: double
          description: Invoiced Amount
          example: '-20.'
        invoicedAmountInCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/paymentReference'
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/refundDetailResource'
        attributes:
          type: object
          description: Custom attributes
          example:
            number: XlQZTmFDFtPFGMxJP6oiAqN3vo+qKZ
        quantity:
          type: integer
          format: int32
          description: Total quantity cancelled
          example: 10
    cancellationResource:
      type: object
      description: Cancellation Resource
      properties:
        cancellationCounter:
          type: string
          description: Cancellation Counter
          example: 1
        source:
          type: string
          description: Determine where the request is initialized
          example: CSR
        reasonCode:
          type: string
          description: Reason code
          example: Order Line Cancel
        subReasonCode:
          type: string
          description: Sub reason code
          example: Late shipping
        status:
          type: string
          description: Cancellation Status
          enum:
            - PROCESSING
            - COMPLETED
            - REJECTED
          example: PROCESSING
        amount:
          type: number
          format: double
          description: Amount
          example: '-20.'
        amountInCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        invoicedAmount:
          type: number
          format: double
          description: Invoiced Amount
          example: '-20.'
        invoicedAmountInCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        payments:
          type: array
          items:
            $ref: '#/components/schemas/paymentReference'
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/refundDetailResource'
        attributes:
          type: object
          description: Custom attributes
          example:
            number: XlQZTmFDFtPFGMxJP6oiAqN3vo+qKZ
    createInvoiceRequest:
      type: object
      description: Create Invoice Request
      properties:
        requestContext:
          $ref: '#/components/schemas/requestReferenceContextResource'
          description: Request reference context information
        invoiceNumber:
          type: string
          description: >-
            Merchant-defined unique invoice number. If omitted, this is
            generated by fabric’s sequence generator using Configuration
            service.
          example: 23940791
        invoiceExternalId:
          type: string
          description: Merchant-defined external optional order identifier
          example: 191763090
        invoiceStatus:
          type: string
          description: Current invoice status
          enum:
            - PENDING
            - CAPTURED
            - SETTLED
            - SETTLE_FAILED
            - PARTIAL_SETTLED
            - APPROVED
            - REJECTED
            - CREATED
          example: CAPTURED
        invoiceType:
          type: string
          description: Invoice type
          example: SHIPPING
        invoicedAt:
          type: string
          format: date-time
          description: System-generated invoice creation time (UTC)
          example: '2022-08-01T20:03:28.483Z'
        shipmentId:
          type: string
          description: >-
            24-character system-generated shipment ID for which invoice is
            generated
          example: 62ff5c0bec0aed3c86202c32
        shipmentNumber:
          type: string
          description: Merchant-specified shipment number for which invoice is generated
          example: 217088603
        shippedAt:
          type: string
          format: date-time
          description: Order shipment time (UTC)
          example: '2022-08-01T20:03:28.483Z'
        orders:
          type: array
          items:
            $ref: '#/components/schemas/invoiceOrder'
        locationNumber:
          type: string
          description: >-
            Unique value to identify ship-from location. This must be the
            `locationNumber` stored in the fabric Location service.
          example: 3235
        location:
          $ref: '#/components/schemas/invoiceLocation'
          description: Location in case of invoice type as shipment
        retail:
          $ref: '#/components/schemas/invoiceRetail'
          description: Optional field retail details
        channelId:
          type: string
          description: Sales channel ID
          example: 10
        invoiceTotal:
          type: number
          format: double
          description: Total invoiced amount captured for the order
          example: 245.7
        invoiceTotalInCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        totalTaxAmount:
          type: number
          format: double
          description: Total tax amount invoiced
          example: 245.7
        totalTaxAmountInCurrencies:
          type: array
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        currency:
          type: string
          description: Currency type in which amount is invoiced
          example: USD
        currencies:
          $ref: '#/components/schemas/currencies'
          description: Customer-defined currency groups supported for order
        customer:
          $ref: '#/components/schemas/invoiceCustomer'
          description: Customer details
        shipInfo:
          $ref: '#/components/schemas/orderShipInfo'
          description: Shipment information
        attributes:
          type: object
          description: Customized attributes to save any additional info
          example:
            attribute1: value
      required:
        - channelId
        - currency
        - invoiceNumber
        - invoiceTotal
        - shipmentId
        - totalTaxAmount
    currencies:
      type: object
      description: currencies
      properties:
        primaryGroup:
          type: string
          description: Primary currency for order
          example: SHOPPER
        groups:
          type: array
          items:
            $ref: '#/components/schemas/currencyGroup'
          maxItems: 50
          minItems: 1
      required:
        - groups
        - primaryGroup
    currencyGroup:
      type: object
      description: CurrencyGroup  details
      properties:
        currency:
          type: string
          description: Currency in ISO-4217
          example: USD
        group:
          type: string
          description: Customer-defined function name which uses this currency.
          example: SHOPPER
        conversionRate:
          type: number
          format: double
          description: conversion rate
          example: 1
        attributes:
          type: object
          description: >-
            Merchant-defined custom attributes. This is a placeholder for
            additional info (in key: value pairs).
          example:
            fxId: ID123
      required:
        - currency
        - group
    discount:
      description: Invoice discount details
      properties:
        amount:
          description: Discounted amount for the given `quantity`
          example: 2
          format: double
          type: number
        amountInCurrencies:
          type: array
          description: >
            The discounted amount represented in one or more currencies.  

            Each entry specifies the value and its corresponding currency
            code,  

            following the structure defined in the `amountInCurrencyResource`
            schema.  

            This enables multi-currency support for the given `quantity`.
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        promotionCode:
          description: >-
            Promotion code used by shoppers to take advantage of an ongoing
            promotion and avail discounts
          example: HNY2022
          type: string
        promotionId:
          description: >-
            Unique promotion ID either from fabric Offers service or external
            Offers service. When fabric Offers service is used, this is the
            24-character system-generated promotion ID returned in the response
            of Create promotion endpoint.
          example: HNY2022
          type: string
        promotionName:
          description: Promotion title or name
          example: Happy New Year
          type: string
        quantity:
          description: Number of discounted items in an order; example- buy 2 get 2 free
          example: 2
          format: int32
          type: integer
        type:
          description: Promotion type
          example: promotion
          type: string
      required:
        - promotionId
      type: object
    errorResponse:
      description: Error response
      properties:
        errors:
          description: Errors
          items:
            $ref: '#/components/schemas/errorResponse'
          type: array
        message:
          description: Error message
          example: Bad request
          type: string
        type:
          description: Error type
          example: CLIENT_ERROR
          type: string
      type: object
    financialPostingAcknowledgeRequest:
      description: Request sample for acknowledging financial transaction
      properties:
        acknowledgedAt:
          description: >-
            Financial transaction acknowledgment time for the invoice. If
            omitted, fabric uses the time (UTC) of invoice acknowledgement call.
          example: 2022-08-01T20:03:28.483Z
          format: date-time
          type: string
        attributes:
          description: >-
            Merchant-defined custom attributes. This is a placeholder for
            additional info in key: value pairs
          example:
            fraudCheckStatus: UPDATED
            fraudStatus: FRAUD_PASS
          type: object
      required:
        - acknowledgedAt
      type: object
    financialPostingAcknowledgeResponse:
      description: Financial transaction acknowledgement response
      properties:
        message:
          description: Generic response
          example: Success
          type: string
      type: object
    invoiceAdjustmentResource:
      description: Invoice adjustment details
      properties:
        adjustmentCounter:
          description: Represents number of times adjustment has happened to the order
          example: 1
          format: int32
          type: integer
        amount:
          type: number
          format: double
          description: Amount
          example: 34.56
        amountInCurrencies:
          type: array
          description: >
            The amount represented in one or more currencies.  

            Each item includes the value and its corresponding currency code,  

            following the structure defined in the `amountInCurrencyResource`
            schema.
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        attributes:
          additionalProperties:
            description: Custom attributes specific to tenant
            type: object
          description: Custom attributes specific to tenant
          type: object
        notes:
          description: An optional free text field and is saved as a metadata
          example: Any additional info
          type: string
        quantity:
          description: Adjustment quantity
          example: 1
          format: int32
          type: integer
        reasonCode:
          description: >-
            Merchant-defined reason code for order adjustment, varies from
            merchant to merchant
          example: Incorrect Item
          type: string
        subReasonCode:
          description: Merchant-defined sub reason code
          example: Late shipping
          type: string
        value:
          description: Amount
          example: 34.56
          format: double
          type: number
      type: object
    invoiceContact:
      description: Contact person's details
      properties:
        email:
          description: Contact person's email
          example: [email protected]
          type: string
        name:
          $ref: '#/components/schemas/orderContactName'
        phone:
          $ref: '#/components/schemas/orderContactPhone'
      type: object
    invoiceCustomer:
      description: Customer details for the generated invoice
      properties:
        accountId:
          description: >-
            Customer's loyalty account ID or external identifier that's used to
            track their loyalty program activity and rewards earned.
          example: 62272e917b12209e68751d94
          type: string
        address:
          $ref: '#/components/schemas/address'
        company:
          description: Shopper's company name. This may be used for company discounts.
          example: Demo Inc
          type: string
        email:
          description: Contact person's email
          example: [email protected]
          type: string
        employeeId:
          description: Employee (ID or name) who initiated an update request
          example: 62272e917b12209e68751d94
          type: string
        name:
          $ref: '#/components/schemas/orderContactName'
        phone:
          $ref: '#/components/schemas/orderContactPhone'
        userId:
          description: >-
            Identifier of the logged in user who initiated the request. This
            could be from either fabric Identity service or an external Identity
            service.
          example: 62272e917b12209e68751d94
          type: string
      type: object
    invoiceFeeDetail:
      description: Invoice fee details
      properties:
        amount:
          description: Amount charged for an item in the invoice
          example: 34.56
          format: double
          type: number
        amountInCurrencies:
          type: array
          description: >
            The amount charged for the item, represented in one or more
            currencies.  

            Each entry specifies the value and its corresponding currency
            code,  

            following the structure defined in the `amountInCurrencyResource`
            schema.
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        quantity:
          description: Quantity of items to which amount is charged
          example: 1
          format: int32
          type: integer
        refundAmount:
          description: Refund amount for the invoice
          example: 345.56
          format: double
          type: number
        refundAmountInCurrencies:
          type: array
          description: >
            The refund amount represented in one or more currencies.  

            Each entry includes the refunded value and its corresponding
            currency code,  

            following the structure defined in the `amountInCurrencyResource`
            schema.
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        type:
          description: Item fee type
          example: tax
          type: string
      type: object
    invoiceItem:
      type: object
      description: Invoice item sample
      properties:
        adjustmentTotal:
          type: number
          format: double
          description: Total price adjustment amount for all items of the order
          example: 123.45
        adjustmentTotalInCurrencies:
          type: array
          description: >
            The total price adjustment amount for the order represented in one
            or more currencies.  

            Each entry includes the adjustment value and its currency code,  

            using the `amountInCurrencyResource` schema.
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        adjustments:
          type: array
          description: Invoice adjustment details for this item
          items:
            $ref: '#/components/schemas/invoiceAdjustmentResource'
        appeasements:
          type: array
          description: Appeasements information, if `invoiceType= APPEASEMENT`
          items:
            $ref: '#/components/schemas/orderAppeasementDetail'
        attributes:
          type: object
          description: Customized attributes
          example:
            key: value
        cancellations:
          type: array
          description: >-
            If `invoiceType= CANCELLATION`, the details of the cancelled items
            will be included in the invoice.
          items:
            $ref: '#/components/schemas/cancellationItemResource'
        currency:
          type: string
          description: Invoiced amount currency
          example: USD
        discounts:
          type: array
          description: Discount applicable for Item
          items:
            $ref: '#/components/schemas/discount'
        fees:
          type: array
          description: Fees charged for individual items of an invoice
          items:
            $ref: '#/components/schemas/invoiceFeeDetail'
        invoiceLineNumber:
          type: integer
          format: int32
          description: >-
            System-specified sequential number iterated for each item in the
            array of the invoice
          example: 3
        invoiceLineTotal:
          type: number
          format: double
          description: Total invoiced amount per line item
          example: 600
        invoiceLineTotalInCurrencies:
          type: array
          description: >
            The total invoiced amount per line item represented in one or more
            currencies.  

            Each entry includes the value and its corresponding currency code,  

            using the `amountInCurrencyResource` schema.
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        invoiceQuantity:
          type: integer
          format: int32
          description: >-
            Total quantity invoiced. If a customer placed an order for 10
            quantities of an item and only 2 got shipped, then 2 is the
            `invoiceQuantity`.
          example: 10
        itemAppeasementTotal:
          type: number
          format: double
          description: Total invoiced appeasement amount per line item
          example: 344.455
        itemAppeasementTotalInCurrencies:
          type: array
          description: >
            The total appeasement amount for the line item represented in one or
            more currencies.  

            Each entry includes the appeasement value and its currency code,  

            using the `amountInCurrencyResource` schema.
          items:
            $ref: '#/components/schemas/amountInCurrencyResource'
        itemCancelTotal:
          type: number
          format: double
          description: Total invoiced cancellation amount per line item
          example: 344.455
        itemCancelTotalInCurrencies:
          type: array
          description: >
            The total cancellation amount for the line item represented in one
            or more currencies.  



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