OpenAPI Specification
openapi: 3.0.0
info:
title: Orderful Conversion Inbox API
description: The official Orderful API documentation.
version: 2.15.0
contact:
name: Orderful
url: https://orderful.com
email: developers@orderful.com
termsOfService: https://orderful.com/terms-and-conditions/
servers:
- url: https://api.orderful.com
tags:
- name: Inbox
description: Retrieve transactions from inboxes.
paths:
/inboxes/{inboxId}/transactions:
get:
operationId: InboxController_list
summary: Inbox
description: 'Retrieves the Transactions from the specified Inbox.
**Note:** The `inboxId` can be found by logging in to [ui.orderful.com](https://ui.orderful.com) and navigating to "Communication Channels".
'
tags:
- Inbox
parameters:
- name: inboxId
required: true
in: path
schema:
type: number
- name: limit
required: false
in: query
description: Value can be `1-100`. Default value is `30`. **Note:** Response size is limited to 200MB. We will return the maximum number of transactions possible without exceeding either the specified `limit` or the maximum response size.
schema:
type: number
- name: orderful-api-version
in: header
description: Specifies the API version to use.
schema:
type: string
default: v4
responses:
'200':
description: Transactions retrieved successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/InboxTransactionsResponseDto'
examples:
purchaseOrders:
summary: Purchase Orders in Inbox
value:
- integrationPayloadId: 019be412-5a85-714c-8ba6-436c1c06efd8
transactionId: 802210971
senderId: MosaicNT
receiverId: MosaicDemo
stream: test
message:
purpose: original
purchaseOrderType: standalone
purchaseOrderNumber: PO-2024-001234
purchaseOrderDate: '2024-02-01'
parties:
billTo:
name: Acme Corporation
addressLine1: 123 Main Street
addressLine2: Accounts Payable
city: Chicago
stateOrProvinceCode: IL
postalCode: '60601'
countryCode: US
contacts:
- type: primary
name: Accounts Payable
phoneNumber: 312-555-0400
email: ap@acme.com
shipTo:
name: Acme Corporation - Warehouse
identificationCode: '987654321'
addressLine1: 456 Warehouse Boulevard
city: Elk Grove Village
stateOrProvinceCode: IL
postalCode: '60007'
countryCode: US
contacts:
- type: primary
name: Receiving Department
phoneNumber: 847-555-0300
buyer:
contacts:
- type: primary
name: John Smith
phoneNumber: 312-555-0100
email: john.smith@acme.com
termsOfSale:
discountDaysDue: 10
netDaysDue: 30
notes:
general:
text:
- Please ensure all items are properly packaged
- Contact receiving department 24 hours before delivery
references:
vendorNumber:
value: VND-456
dates:
requestedDeliveryDate: '2024-02-15'
requestedShipDate: '2024-02-10'
carrierDetails:
routing:
- description: FedEx Ground service
freeOnBoard:
- methodOfPayment: prepaidBySeller
locationType: destination
locationDescription: Dallas, TX
monetaryAmounts:
net: '10000'
lineItems:
- purchaseOrderLineId: '1'
quantity:
value: '100'
unitOfMeasure: each
unitCostPrice: '45.00'
productIds:
vendorItemNumber: GSI-78901
buyerItemNumber: ACME-12345
gtin13: '1234567890123'
dates:
requestedShipDate: '2024-02-10'
- purchaseOrderLineId: '2'
quantity:
value: '250'
unitOfMeasure: case
unitCostPrice: '18.50'
productIds:
vendorItemNumber: GSI-23456
buyerItemNumber: ACME-67890
gtin14: '12345678901234'
outerPack:
numberOfUnits: '25'
dates:
requestedShipDate: '2024-02-10'
- purchaseOrderLineId: '3'
quantity:
value: '50'
unitOfMeasure: each
unitCostPrice: '17.50'
productIds:
vendorItemNumber: GSI-33333
buyerItemNumber: ACME-11111
gtin12: '123456789012'
dates:
requestedShipDate: '2024-02-10'
delivery:
deliveryId: b646771e-a068-4e32-832f-e96f895c5ec9
transactionId: 802210971
href: https://api.orderful.com/transactions/802210971/deliveries/b646771e-a068-4e32-832f-e96f895c5ec9
approve:
href: https://api.orderful.com/transactions/802210971/deliveries/b646771e-a068-4e32-832f-e96f895c5ec9/accept
fail:
href: https://api.orderful.com/transactions/802210971/deliveries/b646771e-a068-4e32-832f-e96f895c5ec9/fail
components:
schemas:
ProductIdDetail:
type: object
properties:
type:
type: string
description: REQUIRED. Product ID type.
value:
type: string
description: REQUIRED. Product ID value.
PhysicalDetails:
type: object
properties:
numberOfUnits:
type: string
packageForm:
type: string
enum:
- carton
- case
- pallet
- bag
- box
- bundle
- drum
- roll
weight:
type: string
weightUnit:
type: string
enum:
- pound
- kilogram
- ounce
- gram
volume:
type: string
volumeUnit:
type: string
860_PURCHASE_ORDER_CHANGE:
type: object
description: Purchase Order Change document - Buyer modifies an existing order.
properties:
purpose:
type: string
description: REQUIRED. Change purpose.
enum:
- change
- cancellation
purchaseOrderType:
type: string
description: PO type.
enum:
- blanketEstimated
- blanketFirm
- dropship
- release
- rushOrder
- standalone
purchaseOrderChangeType:
type: string
description: Type of change.
enum:
- order
- standing
purchaseOrderNumber:
type: string
description: REQUIRED. Original PO number being changed.
purchaseOrderDate:
type: string
format: date
description: REQUIRED. Original PO date.
purchaseOrderChangeDate:
type: string
format: date
description: REQUIRED. Date of the change.
changeSequenceNumber:
type: string
description: Sequence number for tracking multiple changes.
acknowledgmentType:
type: string
description: Acknowledgment request type.
enum:
- withDetail
- withoutDetail
parties:
$ref: '#/components/schemas/Parties'
references:
$ref: '#/components/schemas/References'
dates:
$ref: '#/components/schemas/Dates'
notes:
$ref: '#/components/schemas/Notes'
termsOfSale:
$ref: '#/components/schemas/TermsOfSale'
carrierDetails:
$ref: '#/components/schemas/CarrierDetails'
buyersCurrency:
type: object
properties:
currencyCode:
type: string
lineItems:
type: array
description: REQUIRED. Changed line items.
minItems: 1
items:
$ref: '#/components/schemas/POChangeLineItem'
NoteDetail:
type: object
properties:
description:
type: string
text:
type: array
items:
type: string
description: Note text lines.
InvoiceTaxes:
type: object
description: Invoice tax details (TXI segments).
properties:
harmonizedSalesTax:
description: Harmonized sales tax (TXI01='BE').
allOf:
- $ref: '#/components/schemas/TaxDetails'
goodsAndServicesTax:
description: Goods and services tax (TXI01='GS').
allOf:
- $ref: '#/components/schemas/TaxDetails'
stateProvincialTax:
description: State/provincial tax (TXI01='SP').
allOf:
- $ref: '#/components/schemas/TaxDetails'
stateProvincialGoodsTax:
description: State/provincial goods tax (TXI01='PG').
allOf:
- $ref: '#/components/schemas/TaxDetails'
localTax:
description: Local tax (TXI01='SL' or 'LS').
allOf:
- $ref: '#/components/schemas/TaxDetails'
References:
type: object
description: Reference numbers.
properties:
accountNumber:
$ref: '#/components/schemas/ReferenceDetail'
arrivalCode:
$ref: '#/components/schemas/ReferenceDetail'
associatedPurchaseOrderNumber:
$ref: '#/components/schemas/ReferenceDetail'
reservationNumber:
$ref: '#/components/schemas/ReferenceDetail'
customerOrderNumber:
$ref: '#/components/schemas/ReferenceDetail'
deliveryReference:
$ref: '#/components/schemas/ReferenceDetail'
divisionId:
$ref: '#/components/schemas/ReferenceDetail'
departmentNumber:
$ref: '#/components/schemas/ReferenceDetail'
internalCustomerNumber:
$ref: '#/components/schemas/ReferenceDetail'
vendorNumber:
$ref: '#/components/schemas/ReferenceDetail'
merchandiseTypeCode:
$ref: '#/components/schemas/ReferenceDetail'
promotionNumber:
$ref: '#/components/schemas/ReferenceDetail'
storeNumber:
$ref: '#/components/schemas/ReferenceDetail'
thirdPartyReferenceNumber:
$ref: '#/components/schemas/ReferenceDetail'
warehouseStorageLocation:
$ref: '#/components/schemas/ReferenceDetail'
shipmentNumber:
$ref: '#/components/schemas/ReferenceDetail'
invoiceNumber:
$ref: '#/components/schemas/ReferenceDetail'
Contact:
type: object
properties:
type:
type: string
enum:
- primary
- customerRelations
- orderInquiry
- department
- shipping
- receiving
- hazmat
name:
type: string
phoneNumber:
type: string
faxNumber:
type: string
email:
type: string
AsnCarton:
type: object
description: Carton in shipment.
properties:
trackingNumber:
type: string
serialShippingId:
type: string
description: SSCC-18 code.
cartonPhysicalDetails:
$ref: '#/components/schemas/PhysicalDetails'
specialHandling:
type: array
items:
$ref: '#/components/schemas/SpecialHandlingDetails'
items:
type: array
items:
$ref: '#/components/schemas/AsnItem'
855_PURCHASE_ORDER_ACKNOWLEDGMENT:
type: object
description: Purchase Order Acknowledgment document - Supplier confirms or rejects order.
properties:
purchaseOrderNumber:
type: string
description: REQUIRED. Original PO number being acknowledged (BAK03).
status:
type: string
description: REQUIRED. Overall acknowledgment status (BAK02).
enum:
- accepted
- rejected
statusReasonCode:
type: string
description: Reason code for status.
enum:
- discontinued
- invalidAddress
- invalidBillToCode
- invalidItemNumber
- invalidPrice
- invalidItemQuantity
- invalidShipFrom
- invalidShipMethod
- invalidShipToName
- invalidShipToAddress1
- invalidShipToAddress2
- invalidShipToCity
- invalidShipToStateOrProvince
- invalidShipToPostalCode
- invalidShipToCountry
- itemRecall
- itemSetupIssue
- mainlandOnly
- missingLineItemId
- missingOrderId
- missingShipId
- naturalDisaster
- outOfStock
- seasonalOrEndOfLife
- shippingInFull
- systemIssue
- taxNexusIssue
- transportationIssuePrepaid
- transportationIssueCollect
- undeliverableAddress
- weather
statusNote:
$ref: '#/components/schemas/NoteDetail'
dates:
$ref: '#/components/schemas/POAckDates'
parties:
type: object
properties:
shipFrom:
$ref: '#/components/schemas/Party'
supplier:
$ref: '#/components/schemas/Party'
termsOfSale:
$ref: '#/components/schemas/TermsOfSale'
lineItems:
type: array
description: Acknowledgment line items.
items:
$ref: '#/components/schemas/POAckLineItem'
FOBDetails:
type: object
description: Freight on Board details.
properties:
methodOfPayment:
type: string
enum:
- airCollect
- airPrepaid
- paidByBuyer
- collect
- mutuallyAgreed
- portOfCall
- halfPrepaid
- mixed
- serviceFreightNoCharge
- advancePrepaid
- customerPickupBackhaul
- prepaidChargeCustomer
- prepaidBySeller
- paidBySeller
- pickup
- thirdPartyPay
locationType:
type: string
enum:
- cityAndState
- country
- destination
- origin
- stateProvince
- warehouse
locationDescription:
type: string
description: FOB location description.
titlePassageType:
type: string
enum:
- cityAndState
- country
- destination
- origin
- stateProvince
- warehouse
titlePassageDescription:
type: string
transportationTermsSource:
type: string
enum:
- incoTerms
- tradeTerms
- mutuallyDefined
transportationTerms:
type: string
enum:
- costAndFreight
- costInsuranceAndFreight
- carriageAndInsurancePaidTo
- carriagePaidTo
- deliveredAtFrontier
- deliverDutyPaid
- deliverDutyUnpaid
- deliveredDutyUnpaid
- deliveredExQuay
- deliveredExShip
- domesticallySupplied
- exQuay
- exShip
- exWorks
- freeAlongsideShip
- freeCarrier
- freightCarriageInsurancePaidTo
- freightCarriagePaidTo
- freeOnBoard
- freeOnRail
- freePnTruck
- nonPrivilegedForeign
- privilegedForeign
- mutuallyDefined
riskOfLoss:
type: string
enum:
- toDestinationBuyer
- toFreightEqPointSeller
- toPoolPointSeller
- toDestinationSeller
- mutuallyDefined
description:
type: string
TaxDetails:
type: object
description: Tax details (TXI or TAX segment).
properties:
amount:
type: string
description: Tax amount (TXI02).
percent:
type: string
description: Tax percentage (TXI03).
taxIdNumber:
type: string
description: Tax ID number (TXI09 or TAX01).
locationId:
type: string
description: Location identifier (TAX03).
exemptionCode:
type: string
enum:
- exempt
- notExempt
- notTaxable
jurisdictionType:
type: string
description: Tax jurisdiction type (TXI04).
jurisdictionCode:
type: string
description: Tax jurisdiction code (TXI05).
assignedId:
type: string
description: Assigned identification (TXI10).
AsnOrder:
type: object
description: Order within a shipment.
properties:
purchaseOrderNumber:
type: string
description: REQUIRED. PO number.
releaseNumber:
type: string
purchaseOrderDate:
type: string
format: date
customerOrderNumber:
type: string
parties:
type: object
properties:
markFor:
$ref: '#/components/schemas/Party'
pallets:
type: array
items:
$ref: '#/components/schemas/AsnPallet'
cartons:
type: array
description: Cartons (when not using pallets, SOPI hierarchy).
items:
$ref: '#/components/schemas/AsnCarton'
items:
type: array
description: Items directly on order (no pallets or cartons, SOI hierarchy).
items:
$ref: '#/components/schemas/AsnItem'
InvoiceLineItem:
type: object
description: Invoice line item details.
properties:
purchaseOrderLineId:
type: string
description: Original PO line ID.
quantityInvoiced:
description: REQUIRED. Quantity invoiced.
allOf:
- $ref: '#/components/schemas/Quantity'
unitPrice:
type: string
description: REQUIRED. Unit price (IT104).
extendedPrice:
type: string
description: Extended price (quantity × unit price).
productIds:
description: REQUIRED. Product identifiers.
allOf:
- $ref: '#/components/schemas/ProductIds'
productAttributes:
$ref: '#/components/schemas/ProductAttributes'
shipDate:
type: string
format: date
allowances:
type: array
items:
$ref: '#/components/schemas/AllowanceCharge'
charges:
type: array
items:
$ref: '#/components/schemas/AllowanceCharge'
taxes:
type: array
items:
$ref: '#/components/schemas/TaxDetails'
notes:
$ref: '#/components/schemas/Notes'
ShipmentParties:
type: object
description: Parties involved in shipment.
properties:
shipFrom:
$ref: '#/components/schemas/Party'
shipTo:
$ref: '#/components/schemas/Party'
supplier:
$ref: '#/components/schemas/Party'
InventoryQuantity:
type: object
description: Inventory quantity for a specific location and type.
properties:
locationId:
type: string
description: Location identifier.
type:
type: string
description: Quantity type.
enum:
- available
- allocated
- incoming
- unavailable
- onHand
- committed
quantity:
type: string
description: Quantity value.
availableDate:
type: string
format: date
description: Date when quantity becomes available.
AllowanceCharge:
type: object
properties:
type:
type: string
amount:
type: string
percent:
type: string
description:
type: string
AsnReferences:
type: object
properties:
appointmentNumber:
$ref: '#/components/schemas/ReferenceDetail'
billOfLadingNumber:
$ref: '#/components/schemas/ReferenceDetail'
loadPlanningNumber:
$ref: '#/components/schemas/ReferenceDetail'
pickupReferenceNumber:
$ref: '#/components/schemas/ReferenceDetail'
proNumber:
$ref: '#/components/schemas/ReferenceDetail'
trackingNumber:
$ref: '#/components/schemas/ReferenceDetail'
vendorNumber:
$ref: '#/components/schemas/ReferenceDetail'
ProductIds:
type: object
description: Product identifiers.
properties:
buyerItemNumber:
type: string
vendorItemNumber:
type: string
gtin12:
type: string
gtin13:
type: string
gtin14:
type: string
caseCode:
type: string
drugCode:
type: string
standardBookNumber:
type: string
buyerItemIds:
type: array
items:
$ref: '#/components/schemas/ProductIdDetail'
vendorItemIds:
type: array
items:
$ref: '#/components/schemas/ProductIdDetail'
Parties:
type: object
description: Trading partner information.
properties:
buyer:
$ref: '#/components/schemas/Party'
shipTo:
$ref: '#/components/schemas/Party'
billTo:
$ref: '#/components/schemas/Party'
shipFrom:
$ref: '#/components/schemas/Party'
accountsPayable:
$ref: '#/components/schemas/Party'
soldTo:
$ref: '#/components/schemas/Party'
supplier:
$ref: '#/components/schemas/Party'
856_SHIP_NOTICE_MANIFEST:
type: object
description: Ship Notice / Advanced Shipping Notice (ASN) document - Supplier notifies shipment details.
properties:
purpose:
type: string
description: Transaction purpose.
enum:
- original
- cancellation
- change
shipmentId:
type: string
description: REQUIRED. Unique shipment ID (BSN02).
carrierDetails:
type: object
properties:
quantityAndWeight:
type: array
items:
$ref: '#/components/schemas/CarrierWeightDetails'
routing:
type: array
items:
$ref: '#/components/schemas/RoutingDetails'
equipment:
$ref: '#/components/schemas/EquipmentDetails'
freeOnBoard:
type: array
items:
$ref: '#/components/schemas/FOBDetails'
specialHandling:
type: array
items:
$ref: '#/components/schemas/SpecialHandlingDetails'
references:
$ref: '#/components/schemas/AsnReferences'
dates:
type: object
properties:
shipDate:
type: string
format: date
deliveryDate:
type: string
format: date
shippingPaymentTerms:
type: string
enum:
- prepaidBySeller
- collect
parties:
$ref: '#/components/schemas/ShipmentParties'
allowances:
type: array
items:
$ref: '#/components/schemas/AllowanceCharge'
charges:
type: array
items:
$ref: '#/components/schemas/AllowanceCharge'
orders:
type: array
description: REQUIRED. Orders in this shipment (HL loops).
items:
$ref: '#/components/schemas/AsnOrder'
850_PURCHASE_ORDER:
type: object
description: Purchase Order document - Buyer sends order to supplier.
properties:
purpose:
type: string
description: REQUIRED. Transaction purpose (BEG01).
enum:
- original
- cancellation
- change
- replace
- confirmation
purchaseOrderType:
type: string
description: REQUIRED. PO type (BEG02).
enum:
- blanketEstimated
- blanketFirm
- dropship
- release
- rushOrder
- standalone
purchaseOrderNumber:
type: string
description: REQUIRED. Unique PO number (BEG03).
purchaseOrderDate:
type: string
format: date
description: REQUIRED. PO issue date (BEG05).
contractNumber:
type: string
description: Contract number (BEG06).
releaseNumber:
type: string
description: Release number for blanket orders (BEG04).
acknowledgmentType:
type: string
description: Acknowledgment request type.
parties:
$ref: '#/components/schemas/Parties'
dates:
$ref: '#/components/schemas/Dates'
references:
$ref: '#/components/schemas/References'
termsOfSale:
$ref: '#/components/schemas/TermsOfSale'
carrierDetails:
$ref: '#/components/schemas/CarrierDetails'
notes:
$ref: '#/components/schemas/Notes'
monetaryAmounts:
$ref: '#/components/schemas/HeaderMonetaryAmounts'
conditionsAndRestrictions:
type: array
items:
$ref: '#/components/schemas/Conditions'
lineItems:
type: array
description: REQUIRED. Order line items (PO1 loop).
minItems: 1
items:
$ref: '#/components/schemas/POLineItem'
TermsOfSale:
type: object
description: Payment terms.
properties:
type:
type: string
enum:
- basic
- basicDiscountOffered
- discountNotApplicable
- endOfMonth
- endOfMonth10
- instant
- mutuallyDefined
basisDate:
type: string
enum:
- invoiceDate
- receiptOfGoods
- deliveryDate
- shipDate
- mutuallyDefined
- gageApprovalDate
- specifiedDate
- acceptanceDate
- invoiceTransmissionDate
- effectiveDate
discountPercent:
type: string
discountDaysDue:
type: integer
description: Number of days in the discount period.
discountDueDate:
type: string
format: date
dayOfMonth:
type: integer
netDaysDue:
type: integer
description: Number of days until total invoice amount is due.
netDueDate:
type: string
format: date
discountAmount:
type: string
description: Total discount amount.
description:
type: string
paymentMethodType:
type: string
enum:
- check
- letterOfCredit
- wireTransfer
- corporateTradePayment
- specialAccount
- directPayOthers
Quantity:
type: object
properties:
value:
type: string
description: REQUIRED. Quantity value.
unitOfMeasure:
type: string
enum:
- ball
- assortment
- ocularInsertSystem
- bundle
- bag
- bottle
- belt
- box
- cell
- case
- card
- container
- can
- cartridge
- cassette
- carton
- coil
- combo
- drum
- display
- dozen
- each
- knots
- order
- flakeTon
- foot
- gallon
- gram
- person
- kit
- pound
- linearFoot
- monetaryValue
- milliliter
- meter
- ounce
- threePack
- sixPack
- pail
- pairInches
- piece
- pad
- palletLift
- packPAK
- package
- palletUnitLoad
- pair
- pint
- quart
- reel
- roll
- section
- squareFoot
- sheet
- set
- syringe
- tube
- tote
- thousand
- unit
- vial
InvoiceDates:
type: object
description: Invoice-related dates.
properties:
shipDate:
type: string
format: date
deliveryDate:
type: string
format: date
termsNetDueDate:
type: string
format: date
termsDiscountDueDate:
type: string
format: date
HrefLink:
type: object
required:
- href
properties:
href:
type: string
InventoryDates:
type: object
description: Inventory report date range.
properties:
reportStartDate:
type: string
format: date
reportEndDate:
type: string
format: date
POLineItem:
type: object
description: Purchase order line item.
properties:
purchaseOrderLineId:
type: string
quantity:
$ref: '#/components/schemas/Quantity'
unitCostPrice:
type: string
unitPriceBasis:
type: string
additionalPricing:
type: array
items:
$ref: '#/components/schemas/PricingInfo'
productIds:
description: REQUIRED. Product identifiers.
allOf:
- $ref: '#/components/schemas/ProductIds'
productAttributes:
$ref: '#/components/schemas/ProductAttributes'
outerPack:
$ref: '#/components/schemas/PhysicalDetails'
innerPack:
$ref: '#/components/schemas/PhysicalDetails'
packaging:
type: array
items:
$ref: '#/components/schemas/PackagingDetails'
dates:
$ref: '#/components/schemas/Dates'
references:
$ref: '#/components/schemas/References'
destinationQuantities:
type: array
items:
$ref: '#/components/schemas/DestinationQuantity'
allowances:
type: array
items:
$r
# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/orderful/refs/heads/main/openapi/orderful-inbox-api-openapi.yml