{
"openapi": "3.1.0",
"info": {
"title": "Returns Portal Orders",
"description": "Returns portal allows shoppers to create a return based on their order history. An online experience guides them through creating the return and provides the data needed to receive goods in a warehouse and process eligible refunds.\n\n**When it is used:**\n\n- You post a **Returns Portal Orders** message to Optoro with the full snapshot of the order at the first shipped event of the order. At initial implementation, orders for the previous six months (usually) are posted and then orders are posted as they ship.\n- You post a **Returns Portal Orders** message to Optoro with the full snapshot of the order when order lifecycle events occur. This includes: fulfillments, transactions, adjustments, and order line item modifications. Updates should be as close to real time as possible.\n- You post a **Returns Portal Orders** message to Optoro when the order and/or items within the order are refunded. However, when the order is an exchange one, you should not neccesarily receive refunds.\n",
"version": "3.0.0"
},
"servers": [
{
"url": "https://orders.sandbox.optiturn.com",
"description": "Sandbox"
}
],
"paths": {
"/returns_portal_orders": {
"post": {
"summary": "Create Returns Portal Orders",
"operationId": "returns_portal_orders",
"parameters": [
{
"in": "header",
"name": "Api-Version",
"schema": {
"type": "string",
"enum": [
"3"
]
},
"required": true
}
],
"requestBody": {
"description": "A Returns Portal Order object",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/returns_portal_orders"
}
}
}
},
"responses": {
"200": {
"description": "Success"
}
}
}
}
},
"components": {
"schemas": {
"product_variant": {
"required": [
"attributes",
"allow_backorder",
"product_identifier",
"variant_identifier",
"product_amount_cents",
"quantity_in_stock",
"inventory_managed_by_platform",
"title"
],
"type": "object",
"properties": {
"attributes": {
"description": "A list of attributes that describe the variant. Such as colors or sizes. See variant attributes.",
"type": "array",
"items": {
"required": [
"name",
"value"
],
"type": "object",
"properties": {
"name": {
"description": "Name of attribute describing the variant.",
"type": "string"
},
"value": {
"description": "Value of the attribute name.",
"type": "string"
}
}
},
"example": [
{
"name": "Color",
"value": "Green"
},
{
"name": "Size",
"value": "XL"
}
]
},
"allow_backorder": {
"description": "Specifies if the variant is allowed to be backordered if out of stock.",
"type": "boolean"
},
"product_identifier": {
"description": "Id unique to that product (ex. same SKU from different vendors). Send SKU if no product_identifier exists.",
"type": "string",
"example": "1234-5678"
},
"variant_identifier": {
"description": "Id unique to that variant. product_identifier can be the same as variant_identifier in some systems. Send SKU if no variant_identifier exists.",
"type": "string",
"example": "1234-5678"
},
"product_amount_cents": {
"description": "Unit price amount in cents for a single unit of a product.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"currency": {
"description": "Currency code. Must be ISO-4217 reference. E.g. \"USD\".",
"type": "string",
"example": "USD"
},
"quantity_in_stock": {
"description": "The quantity in stock for the specific variant.",
"type": "integer",
"example": 2
},
"inventory_managed_by_platform": {
"description": "True if Inventory is managed by Returns Portal provider.",
"type": "boolean"
},
"sku": {
"description": "The SKU for the variant.",
"type": "string",
"example": "888812345678"
},
"title": {
"description": "The title for the variant",
"type": "string",
"example": "Fuzzy green t-shirt"
},
"unit_price_amount_cents": {
"description": "Unit price amount in cents of a single unit of a product.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"image_urls": {
"description": "An array of image strings associated with the given parent.",
"type": "array",
"items": {
"type": "string"
},
"example": [
"https://example.com/img-1.jpg",
"https://example.com/img-2.jpg"
]
},
"image_hash": {
"description": "Hash value of the product image.",
"type": "string",
"example": "14758f1afd44c09b7992073ccf00b43d"
},
"weight": {
"description": "Product weight, in lbs.",
"type": "number",
"example": 2.2
},
"height": {
"description": "Product height, in inches.",
"type": "number",
"example": 1.2
},
"width": {
"description": "Product width, in inches.",
"type": "number",
"example": 3.5
},
"length": {
"description": "Product length, in inches.",
"type": "number",
"example": 6.4
},
"product_url": {
"description": "Product page link.",
"type": "string",
"example": "https://example.com/fuzzy-green"
},
"harmonized_system_code": {
"description": "Product harmonized system code",
"type": "string"
},
"country_code_of_origin": {
"description": "Used in conjunction with harmonized system code for International Returns",
"type": "string"
}
}
},
"item": {
"required": [
"identifier",
"quantity",
"quantity_shipped",
"quantity_canceled",
"product_identifier",
"variant_identifier",
"title",
"tags",
"product_amount_cents",
"tax_amount_cents",
"discount_amount_cents",
"unit_price_amount_cents"
],
"type": "object",
"properties": {
"identifier": {
"description": "ID for individual item within the Order. Must be a unique value per item.",
"type": "string",
"example": "123"
},
"concept": {
"description": "A unique identifier for the retail \"concept\" or \"brand\" to which the product belongs. This differentiates similar products when the your company has multiple retail concepts. Must work with Professional Services when using this field to uniquely identify catalog entries.\n",
"type": "string",
"example": "Best Brand"
},
"upc": {
"description": "UPC that represents the product for this order item. Required unless SKU is present.",
"type": "string",
"example": "888812345678"
},
"sku": {
"description": "An identifier which matches the catalog and represents the product for this order item. Required unless UPC is present.",
"type": "string",
"example": "888812345678"
},
"quantity": {
"description": "Number of units of a particular line item that has been ordered. Must be less than or equal to 1000. Must be greater than or equal to the sum of quantity_shipped and quantity_canceled.",
"type": "integer",
"example": 2
},
"quantity_shipped": {
"description": "Number of units of a particular line item that have shipped. Must be less than or equal to quantity.",
"type": "integer"
},
"quantity_canceled": {
"description": "Number of units of a particular line item that have been canceled. Must be less than or equal to quantity.",
"type": "integer"
},
"quantity_refunded": {
"description": "Number of units of a particular line item that have already been refunded. Must be less than or equal to quantity_shipped.",
"type": "integer"
},
"tracking_number": {
"description": "The tracking number for the package containing this order item. This allows operations to scan the tracking number for undeliverable items.",
"type": "string",
"example": "1Z9999999999999999"
},
"reverse_tracking_number": {
"description": "The return tracking number for the package containing this order item. This allows operations to scan the tracking number for items returned by the customer.",
"type": "string",
"example": "1Z9999999999999999"
},
"dropship_identifier": {
"description": "ID used to track item that was drop shipped.",
"type": "string",
"example": "4441212"
},
"shipped_date": {
"description": "Date when the order was shipped, in ISO 8601 format, UTC.",
"type": "string",
"example": "2018-08-30T15:39:42.025Z"
},
"return_policy_end_date": {
"description": "Date when the order item is no longer eligible for return, in ISO 8601 format, UTC.",
"type": "string",
"example": "2018-08-30T15:39:42.025Z"
},
"product_identifier": {
"description": "Id unique to that product (ex. same SKU from different vendors). Send SKU if no product_identifier exists.",
"type": "string",
"example": "1234-5678"
},
"variant_identifier": {
"description": "Variant can help disambiguate specific variant of a product class (e.g. blue color of a sweater product) -- product_identifier can be the same as variant_identifier in some systems. Send SKU if no variant_identifier exists.",
"type": "string",
"example": "1234-5678"
},
"variants": {
"description": "Array of product variants for the parent item. Including variants improves exchange functionality in the return portal.",
"type": "array",
"items": {
"$ref": "#/components/schemas/product_variant"
}
},
"title": {
"description": "Title of product",
"type": "string",
"example": "Fuzzy red t-shirt"
},
"product_amount_cents": {
"description": "Raw product amount without taxes or discounts. Sum of all the units for that line item (quantity x unit_price_amount for a given product).",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"tax_amount_cents": {
"description": "Line item tax amount in cents.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"discount_amount_cents": {
"description": "Line item discount amount in cents.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"unit_price_amount_cents": {
"description": "Unit price amount in cents of a single unit of a product.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"tags": {
"description": "An array of tags associated with the given order. Current supported tags are: FinalSale, gift-card, canceled, Thirdparty, pickup_in_store, cs-required",
"type": "array",
"items": {
"type": "string"
}
},
"image_url": {
"description": "Product image file link.",
"type": "string",
"example": "https://example.com/img.jpg"
},
"weight": {
"description": "Product weight, in lbs.",
"type": "number",
"example": 2.2
}
}
},
"customer": {
"required": [
"identifier",
"email"
],
"description": "Customer who placed order.",
"type": "object",
"properties": {
"identifier": {
"description": "Reference to customer record in your OMS",
"type": "string",
"example": "123"
},
"first_name": {
"description": "Customer first name",
"type": "string",
"example": "Carmine"
},
"last_name": {
"description": "Customer last name",
"type": "string",
"example": "Customer"
},
"email": {
"description": "Customer contact email",
"type": "string",
"example": "customer@example.com"
},
"phone": {
"description": "Customer phone",
"type": "string",
"example": "202-555-1212"
}
}
},
"address": {
"required": [
"name",
"street1",
"city",
"state",
"zip_code",
"country_code"
],
"type": "object",
"properties": {
"name": {
"description": "Name of person.",
"type": "string",
"example": "Carmine Customer"
},
"street1": {
"description": "The street address.",
"type": "string",
"example": "123 Fake St."
},
"street2": {
"description": "An optional second line for the street address, for suite or other similar additions.",
"type": "string",
"example": "STE 1200"
},
"city": {
"description": "The city for this address.",
"type": "string",
"example": "Utiopiannapolis"
},
"state": {
"description": "The state or province for this address.",
"type": "string",
"example": "WA"
},
"zip_code": {
"description": "The zip or postal code for this address.",
"type": "string",
"example": "99877"
},
"country_code": {
"description": "The country code for this address.",
"type": "string",
"example": "US"
},
"phone": {
"description": "Phone number.",
"type": "string",
"example": "202-555-1212"
}
}
},
"payment_details": {
"type": "object",
"properties": {
"avs_result_code": {
"description": "Response code from credit card company for correct AVS",
"type": "string"
},
"cvv_result_code": {
"description": "Response code from credit card company for correct CVV",
"type": "string"
},
"credit_card_company": {
"type": "string"
},
"gift_card_id": {
"type": "string"
},
"gift_card_code": {
"type": "string"
}
}
},
"transaction": {
"required": [
"identifier",
"parent_identifier",
"amount_cents",
"status",
"type",
"gateway",
"is_online",
"is_test",
"created_at",
"updated_at",
"payment_details"
],
"type": "object",
"properties": {
"identifier": {
"description": "Unique identifier for a transaction. These details are used to reconcile instant exchanges.",
"type": "string",
"example": "adf56c018de8438dbc7d86017cc10f1d"
},
"parent_identifier": {
"type": "string",
"example": "a0bf7bddb0928a7e69b51110c14831c0"
},
"amount_cents": {
"description": "Raw amount of a particular transaction - all transactions amounts in a given order should sum to order amount.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"status": {
"description": "Current status of the transaction. E.g. \"PENDING\" \"SUCCESS\" \"FAILURE\".",
"type": "string",
"example": "PENDING"
},
"type": {
"description": "Type refers to credit/debit from merchants point of view. E.g. \"AUTHORIZATION\" \"CAPTURE\" \"SALE\" \"REFUND\" \"VOID\".",
"type": "string",
"example": "CAPTURE"
},
"gateway": {
"description": "Name of the payment gateway.",
"type": "string",
"example": "QuikPay"
},
"is_online": {
"description": "Denotes if the transaction is programmatically reversible.",
"type": "boolean"
},
"is_test": {
"description": "Denotes if the transaction is a test.",
"type": "boolean"
},
"created_at": {
"description": "Creation date in ISO 8601 format, UTC.",
"type": "string",
"example": "2018-08-30T15:39:42.025Z"
},
"updated_at": {
"description": "Last updated date in ISO 8601 format, UTC.",
"type": "string",
"example": "2018-08-30T15:39:42.025Z"
},
"payment_details": {
"description": "Additional details regarding gateway and transaction",
"type": "object",
"$ref": "#/components/schemas/payment_details"
}
}
},
"refund_line_item": {
"required": [
"identifier",
"quantity",
"order_item_identifier"
],
"type": "object",
"properties": {
"identifier": {
"description": "ID for individual item within the Refund. Must be a unique value per item.",
"type": "string",
"example": "RF12554113"
},
"quantity": {
"description": "Quantity of products refunded for the order item.",
"type": "integer",
"example": 2
},
"order_item_identifier": {
"description": "Order item identifier for product that has been refunded.",
"type": "string",
"example": "123"
}
}
},
"refund": {
"required": [
"identifier",
"refund_transactions",
"total_refund_amount_cents",
"refund_line_items",
"created_at"
],
"type": "object",
"properties": {
"identifier": {
"description": "Unique identifier for the refund.",
"type": "string",
"example": "RF12554113"
},
"total_refund_amount_cents": {
"description": "The total amount refunded for the returned items.",
"type": "integer",
"format": "int",
"minimum": 0
},
"refund_line_items": {
"description": "List of line items included in the refund.",
"type": "array",
"items": {
"$ref": "#/components/schemas/refund_line_item"
}
},
"note": {
"description": "Description of the refund.",
"type": "string"
},
"created_at": {
"description": "Creation date in ISO 8601 format, UTC.",
"type": "string",
"example": "2018-08-30T15:39:42.025Z"
},
"rma_identifier": {
"description": "Identifier of the RMA. Used to help disambiguate if there are multiple RMAs for the same order.",
"type": "string",
"example": "RMA12345"
},
"tags": {
"description": "Tags associated with the given refund. Current supported tags are:
- `ignore_refund`: refund is ignored and does not influence return eligibility
",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"discount": {
"required": [
"identifier",
"code",
"amount_cents",
"created_at"
],
"type": "object",
"properties": {
"identifier": {
"type": "string"
},
"code": {
"type": "string"
},
"type": {
"description": "Discount type. E.g. \"Fixed_amount\", \"Percentage\", \"Shipping\", \"Bonus\", \"Fixed_Price\", \"Alt_Pricing\".",
"type": "string",
"example": "Percentage"
},
"amount_cents": {
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"created_at": {
"description": "Creation date in ISO 8601 format, UTC.",
"type": "string",
"example": "2018-08-30T15:39:42.025Z"
},
"updated_at": {
"description": "Last updated date in ISO 8601 format, UTC.",
"type": "string",
"example": "2018-08-30T15:39:42.025Z"
}
}
},
"order": {
"required": [
"identifier",
"status",
"total_amount_cents",
"product_amount_cents",
"tax_amount_cents",
"discount_amount_cents",
"shipping_amount_cents",
"shipping_tax_amount_cents",
"currency",
"tags",
"created_at",
"updated_at",
"items",
"customer",
"shipping_address",
"billing_address",
"transactions",
"refunds",
"discounts"
],
"type": "object",
"properties": {
"identifier": {
"description": "Public facing identifier for this order. Must be a unique value per order.",
"type": "string",
"example": "1455123AB12"
},
"concept": {
"description": "A unique identifier for the retail ‘concept’ or ‘brand’ to which the product belongs. This differentiates similar products when the your company has multiple retail concepts. Must work with Professional Services when using this field to uniquely identify catalog entries.\n",
"type": "string",
"example": "Best Brand"
},
"raw_status": {
"description": "Order status in raw form",
"type": "string",
"example": "processing"
},
"status": {
"description": "Status of the order as it relates to the RMA portal",
"type": "string",
"enum": [
"Created",
"Shipped",
"Canceled"
],
"example": "Shipped"
},
"total_amount_cents": {
"description": "Total order amount including taxes and discounts and shipping.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"product_amount_cents": {
"description": "Total order amount of merchandise purchased.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"tax_amount_cents": {
"description": "Total order amount of sales tax on merchandise.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"discount_amount_cents": {
"description": "Total order amount of discounts.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"shipping_amount_cents": {
"description": "Total order amount of shipping costs.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"shipping_tax_amount_cents": {
"description": "Total order amount of sales tax on shipping.",
"type": "integer",
"format": "int",
"minimum": 0,
"example": 100
},
"currency": {
"description": "Currency code. Must be ISO-4217 reference. E.g. \"USD\"",
"type": "string",
"example": "USD"
},
"tags": {
"description": "An array of tags associated with the given order. Current supported tags are: FinalSale, gift-card, canceled, Thirdparty, ShippingRateOverride, pickup_in_store",
"type": "array",
"items": {
"type": "string"
}
},
"note": {
"description": "Arbitrary context notes (discount notes, etc.)",
"type": "string",
"example": "This order was delayed."
},
"created_at": {
"description": "Creation date in ISO 8601 format, UTC",
"type": "string",
"example": "2018-08-30T15:39:42.025Z"
},
"updated_at": {
"description": "Last updated date in ISO 8601 format, UTC",
"type": "string",
"example": "2018-08-30T15:39:42.025Z"
},
"items": {
"description": "An array of order line items.",
"type": "array",
"items": {
"$ref": "#/components/schemas/item"
}
},
"customer": {
"description": "Customer",
"allOf": [
{
"$ref": "#/components/schemas/customer"
},
{
"type": "object",
"properties": {
"tags": {
"description": "Tags associated with the customer",
"type": "array",
"items": {
"type": "string"
},
"example": [
"Tier 1",
"Tier 2"
]
}
}
}
]
},
"shipping_address": {
"description": "Reduce customer friction by auto populating package sender details in the return label for the shopper.",
"type": "object",
"$ref": "#/components/schemas/address"
},
"billing_address": {
"description": "Customer billing address will help support exchange orders.",
"type": "object",
"$ref": "#/components/schemas/address"
},
"transactions": {
"description": "Enables uneven exchanges across multiple payments methods (gift cards). If no data is available, send an empty array. If an object is provided, it must be valid.",
"type": "array",
"items": {
"$ref": "#/components/schemas/transaction"
}
},
"refunds": {
"description": "Refunds associated with line items on the order. Helps avoid customers getting double-refunds through multiple channels. For any items on order that are refunded outside of Optoro (e.g. customer call). Refund objects are not updatable. If no data is available, send an empty array. If an object is provided, it must be valid.",
"type": "array",
"items": {
"$ref": "#/components/schemas/refund"
}
},
"discounts": {
"description": "Details of any discounts (coupons or offers) that may affect the shoppers refund amount. If no data is available, send an empty array. If an object is provided, it must be valid.",
"type": "array",
"items": {
"$ref": "#/components/schemas/discount"
}
}
}
},
"returns_portal_orders": {
"type": "object",
"required": [
"returns_portal_order"
],
"properties": {
"returns_portal_order": {
"description": "An orders object.",
"type": "object",
"required": [
"orders"
],
"properties": {
"orders": {
"description": "Array of orders.",
"type": "array",
"items": {
"$ref": "#/components/schemas/order"
}
}
}
}
}
}
}
}
}