openapi: 3.0.1
info:
title: Cart Actions Endpoints Payments 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: Payments
description: Payments endpoints are used to add add, update and remove payments from the Cart.
paths:
/carts/{cartId}/payments:
post:
tags:
- Payments
summary: Create Payment
description: 'Adds a payment method to the corresponding cart to process a transaction.
The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
'
operationId: createPayment
parameters:
- 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/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
- name: x-fabric-tenant-id
in: header
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. \n"
required: true
schema:
type: string
example: 617329dfd5288b0011332311
- name: x-fabric-request-id
in: header
description: ' Unique request ID for tracking.'
required: false
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
- name: x-fabric-channel-id
in: header
description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
required: false
schema:
type: string
example: '12'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePaymentRequest'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/NewPayment'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Cart or Payment not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
/carts/{cartId}/payments/{id}/actions/delete-attributes:
post:
tags:
- Payments
summary: Delete Payment Attributes
description: 'Partially deletes attributes of your choice in the payment object associated with the corresponding cart.
The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The ID from the [Create payment](/v3/cart-and-checkout/api-reference/carts-v3/payments/create-payments) endpoint is used in the path parameter.
'
operationId: deletePaymentAttributes
parameters:
- 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/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
- name: id
in: path
required: true
schema:
type: string
description: The Payment ID that was generated when a payment was created using the [Create payment](/v3/cart-and-checkout/api-reference/carts-v3/payments/create-payments) endpoint.
- name: x-fabric-tenant-id
in: header
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. \n"
required: true
schema:
type: string
example: 617329dfd5288b0011332311
- name: x-fabric-request-id
in: header
description: ' Unique request ID for tracking.'
required: false
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
- name: x-fabric-channel-id
in: header
description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
required: false
schema:
type: string
example: '12'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAttributesRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Cart or Payment not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
/carts/{cartId}/payments/{id}/actions/add-attributes:
post:
tags:
- Payments
summary: Add Payment Attributes
description: 'Partially updates attributes of your choice in the payment.
The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The ID from the [Create payment](/v3/cart-and-checkout/api-reference/carts-v3/payments/create-payments) endpoint is used in the path parameter.
'
operationId: addPaymentAttributes
parameters:
- 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/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
- name: id
in: path
required: true
schema:
type: string
description: The Payment ID that was generated when a payment was created using the [Create payment](/v3/cart-and-checkout/api-reference/carts-v3/payments/create-payments) endpoint.
- name: x-fabric-tenant-id
in: header
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. \n"
required: true
schema:
type: string
example: 617329dfd5288b0011332311
- name: x-fabric-request-id
in: header
description: ' Unique request ID for tracking.'
required: false
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
- name: x-fabric-channel-id
in: header
description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
required: false
schema:
type: string
example: '12'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddAttributesRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Cart or Payment not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
/carts/{cartId}/payments/{id}:
delete:
tags:
- Payments
summary: Delete Payment
description: 'Removes the payment from the cart.
The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The ID from the [Create payment](/v3/cart-and-checkout/api-reference/carts-v3/payments/create-payments) endpoint is used in the path parameter.
'
operationId: removePayment
parameters:
- 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/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
- name: id
in: path
required: true
schema:
type: string
description: The Payment ID that was generated when a payment was created using the [Create payment](/v3/cart-and-checkout/api-reference/carts-v3/payments/create-payments) endpoint.
- name: x-fabric-tenant-id
in: header
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. \n"
required: true
schema:
type: string
example: 617329dfd5288b0011332311
- name: x-fabric-request-id
in: header
description: ' Unique request ID for tracking.'
required: false
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
- name: x-fabric-channel-id
in: header
description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
required: false
schema:
type: string
example: '12'
responses:
'204':
description: No Content
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Cart or Payment not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
patch:
tags:
- Payments
summary: Update Payment
description: 'Updates the payment in the cart.
The Cart ID from the [Create cart](/v3/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint is used in the path parameter.
The ID from the [Create payment](/v3/cart-and-checkout/api-reference/carts-v3/payments/create-payments) endpoint is used in the path parameter.
'
operationId: updatePayment
parameters:
- 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/cart-and-checkout/api-reference/carts-v3/carts/carts) endpoint.
- name: id
in: path
required: true
schema:
type: string
description: The Payment ID that was generated when a payment was created using the [Create payment](/v3/cart-and-checkout/api-reference/carts-v3/payments/create-payments) endpoint.
- name: x-fabric-tenant-id
in: header
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. \n"
required: true
schema:
type: string
example: 617329dfd5288b0011332311
- name: x-fabric-request-id
in: header
description: ' Unique request ID for tracking.'
required: false
schema:
type: string
example: 263e731c-45c8-11ed-b878-0242ac120002
- name: x-fabric-channel-id
in: header
description: x-fabric-channel-id identifies the sales channel through which the API request is being made; primarily for multichannel use cases. It is a required field. The default US channel is 12 while the default Canada channel is 11.
required: false
schema:
type: string
example: '12'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePaymentRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Payment'
'400':
description: Client error
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
'404':
description: Cart or Payment not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
/orders/actions/authorize-payments:
post:
description: This endpoint is used synchronously or asynchronously for authorizing order payments pending for authorization.
operationId: authorizeOrderPayments
parameters:
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/paymentAuthorizationRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/paymentAuthorizationResponse'
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'400':
content:
application/json:
example:
errors:
- message: Invalid request
type: CLIENT_ERROR
message: Bad request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'401':
content:
application/json:
example:
message: Unauthorized request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'404':
content:
application/json:
example:
message: Not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Not found
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'500':
content:
application/json:
example:
message: Internal server error
type: SERVER_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
summary: Authorize Order Payments
tags:
- Payments
/orders/order-number/{orderNumber}/actions/update-payment-status:
post:
description: This endpoint is used sync order payments when transactions happen externally. Additionally, used for updating order payment status and the amount, whether it is captured, refunded or void amount. <p> If you don't have order number, use the corresponding order ID-based endpoint - POST /orders/{orderId}/actions/update-payment-status. </p>
operationId: updatePaymentStatusByOrderNumber
parameters:
- description: Merchant-defined order identifier
example: 123k4h123k
in: path
name: orderNumber
required: true
schema:
type: string
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/updatePaymentRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/orderResponse'
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'400':
content:
application/json:
example:
errors:
- message: Invalid request
type: CLIENT_ERROR
message: Bad request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'401':
content:
application/json:
example:
message: Unauthorized request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'404':
content:
application/json:
example:
message: Not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Not found
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'500':
content:
application/json:
example:
message: Internal server error
type: SERVER_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
summary: Update Status of Order Payment by Order Number
tags:
- Payments
/orders/{orderId}/actions/update-payment-status:
post:
description: This endpoint is used sync order payments when transactions happen externally. Additionally, used for updating order payment status and the amount, whether it is captured, refunded or void amount. <p> If you don't have order ID, use the corresponding order number-based endpoint - POST /orders/order-number/{orderNumber}/actions/update-payment-status.</p>
operationId: updatePaymentStatus
parameters:
- description: 24-character system-generated ID. It is returned in the response of Create Order - `POST /orders` endpoint.
example: 5349b4ddd2781d08c09890f4
in: path
name: orderId
required: true
schema:
type: string
- $ref: '#/components/parameters/xFabricTenantId'
- $ref: '#/components/parameters/xFabricChannelId'
- $ref: '#/components/parameters/xFabricRequestId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/updatePaymentRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/orderResponse'
description: OK
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'400':
content:
application/json:
example:
errors:
- message: Invalid request
type: CLIENT_ERROR
message: Bad request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Bad request
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'401':
content:
application/json:
example:
message: Unauthorized request
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Unauthorized
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'404':
content:
application/json:
example:
message: Not found
type: CLIENT_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Not found
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
'500':
content:
application/json:
example:
message: Internal server error
type: SERVER_ERROR
schema:
$ref: '#/components/schemas/errorResponse'
description: Internal server error
headers:
x-fabric-request-id:
$ref: '#/components/headers/xFabricRequestIdResponseHeader'
summary: Update Order Payment Status by Order ID
tags:
- Payments
components:
schemas:
itemFulfillmentResource:
type: object
description: Item fulfillment model
properties:
isFulfillable:
type: boolean
default: 'true'
description: Indicates whether the item can be fulfilled based on its current state and configuration.
example: true
isInventoryManaged:
type: boolean
default: 'true'
description: To identify if an inventory is managed or not for the respective item
example: true
locationNumber:
type: string
description: Location number
example: 123
shipFromAddress:
$ref: '#/components/schemas/address'
trackingDetails:
$ref: '#/components/schemas/trackingDetailsResource'
description: Tracking details for the shipment
attributes:
type: object
additionalProperties:
type: object
description: Custom attributes for this item
example:
attribute1: value
paymentAuthorizationResponse:
description: Response model for Payment Authorization request
properties:
orders:
description: orders object
items:
$ref: '#/components/schemas/orderPaymentAuthorizationResource'
type: array
type: object
NewPayment:
type: object
properties:
id:
type: string
description: The unique identifier for the payment generated in this response, used for referencing in other endpoints.
example: 6ef2067a-5d6b-4785-a090-96ea0078220d
provider:
type: string
description: The payment provider, such as Verifone, that offers functions like transaction processing, gateway management, and other financial services.
example: verifone
processor:
type: string
description: The payment processor, such as Stripe, responsible for handling and processing payment transactions by facilitating communication between the merchant and the issuing bank.
example: stripe
method:
type: string
description: Payment method, such as Apple Pay, used for processing transactions.
example: apple pay
methodType:
type: string
description: Payment method type, such as a credit card.
example: credit card
state:
type: string
description: Payment state indicates whether the payment has been successfully processed.
example: PENDING
enum:
- PENDING
- AUTHORIZED
- CAPTURED
- FAILED
authorization:
$ref: '#/components/schemas/PaymentAuthorization'
billToAddress:
type: string
description: The Address ID that was generated when an address was created using the [Create address](/v3/cart-and-checkout/api-reference/carts-v3/addresses/create-addresses) endpoint.
example: a8577d7f-0d4d-4b22-8e85-7b4a2e90dc93
cardDetails:
type: object
description: Information about the card used for payment, such as gift card details.
additionalProperties:
type: object
description: Information about the card used for payment, such as gift card details.
attributes:
type: object
additionalProperties:
type: object
description: Custom attributes associated with the transaction, such as the name of the gift card used.
example:
gift-card-name: custom name
description: Custom attributes associated with the transaction, such as the name of the gift card used.
example:
gift-card-name: custom name
description: Cart Payment
ClientError:
type: object
properties:
type:
type: string
description: Error code, meant for machine consumption
example: BAD_REQUEST
message:
type: string
description: Human-readable error description
example: x-fabric-tenant-id is required
description: Client error details
amountInCurrency:
description: Amount in currency object details.
properties:
amount:
description: The amount displayed in the primary currency.
example: 123.45
format: double
type: number
currency:
description: Currency in ISO-4217
example: USD
type: string
group:
description: A unique identifier for currencies. All calculations and invoicing are based on this identifier. For example, the `Shopper` group uses USD, while the `Retailer` group uses EUR.
example: SHOPPER
type: string
required:
- currency
- group
type: object
quantityInStatus:
description: Item quantity for each status
properties:
cancelled:
description: Cancelled quantity of given item
example: 10
format: int32
type: integer
created:
description: Ordered quantity of given item
example: 10
format: int32
type: integer
delivered:
description: Delivered quantity of given item
example: 10
format: int32
type: integer
hold:
description: Held quantity of given item
example: 10
format: int32
type: integer
pendingShipped:
description: Pending quantity of given item
example: 10
format: int32
type: integer
returned:
description: Returned quantity of given item
example: 10
format: int32
type: integer
shipped:
description: Shipped quantity of given item
example: 10
format: int32
type: integer
type: object
trackingDetailsResource:
type: object
description: Tracking details
properties:
trackingNumber:
type: string
description: Tracking number
example: 1ZH4E331YW37690225
trackingURL:
type: string
description: Tracking URL
example: https://www.ups.com/track?tracknum=1ZH4E331YW37690225
AddAttributesRequest:
required:
- attributes
type: object
properties:
attributes:
type: object
additionalProperties:
type: object
description: An object containing custom attributes of your choice for the resource.
example:
test: test
description: An object containing custom attributes of your choice for the resource.
example:
test: test
description: Add Attributes Request
orderDiscount:
description: An object containing all the discount details for an order.
properties:
amount:
description: Discounted amount for the given `quantity` within an order.
example: 2.99
format: double
type: number
amountInCurrencies:
items:
description: Discounted amount for the given `quantity`, itemized by each currency used within the order.
$ref: '#/components/schemas/amountInCurrencyResource'
type: array
invoiceQuantity:
description: Total quantity invoiced. If customer placed order for 10 quantity of an item and only 2 got shipped, then 2 is the `invoiceQuantity`.
example: 10
format: int32
type: integer
promotionCode:
description: Promotion code used by shoppers to take advantage of an ongoing promotion.
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 t
# --- truncated at 32 KB (130 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fabric-com/refs/heads/main/openapi/fabric-com-payments-api-openapi.yml