Issue and manage invoices generated from shipped or fulfilled orders. The Invoices API captures the financial event tied to an order's fulfillment and is the integration point for ERP, tax, and finance systems consuming fabric order data.
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: test@example.com
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: test@example.com
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: test@example.com
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: test@example.com
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