BACK-288 - Document backorder settings

reference/inventory.v3.yml

@@ -538,6 +538,12 @@ components:
                 description: |
                   Warehouse location identifier; bin picking number for the item.
                 example: "1"
+              backorder_message_id:
+                type: integer
+                nullable: true
+                description: |
+                  ID of the backorder message to associate with this item. Set to null to use the default message. Only applicable when backordering is enabled for the store.
+                example: 1
       required:
         - settings
     LocationItemsResponse:
@@ -590,6 +596,38 @@ components:
               description: |
                 Warehouse location identifier; bin picking number for the item.
               example: "1"
+            backorder_message:
+              type: object
+              nullable: true
+              description: |
+                Backorder message information for the item. This field is only present when a custom backorder message is assigned to the item. Only present when backordering is enabled for the store.
+              properties:
+                id:
+                  type: integer
+                  description: Unique identifier for the backorder message.
+                  example: 1
+                name:
+                  type: string
+                  description: Name of the backorder message.
+                  example: "Backorder Notice"
+                message:
+                  type: string
+                  description: The actual message text to display.
+                  example: "This item is currently out of stock and will ship when available."
+                is_default:
+                  type: boolean
+                  description: Whether this is the default message.
+                  example: false
+                created_at:
+                  type: string
+                  format: date-time
+                  description: Timestamp when the message was created.
+                  example: "2025-01-15T10:30:00Z"
+                updated_at:
+                  type: string
+                  format: date-time
+                  description: Timestamp when the message was last updated.
+                  example: "2025-01-20T14:22:00Z"
     ItemResponse:
       type: object
       properties:
@@ -657,6 +695,38 @@ components:
                     type: string
                     description: Warehouse location identifier; bin picking number for the item.
                     example: "1"
+                  backorder_message:
+                    type: object
+                    nullable: true
+                    description: |
+                      Backorder message information for the item. This field is only present when a custom backorder message is assigned to the item. Only present when backordering is enabled for the store.
+                    properties:
+                      id:
+                        type: integer
+                        description: Unique identifier for the backorder message.
+                        example: 1
+                      name:
+                        type: string
+                        description: Name of the backorder message.
+                        example: "Backorder Notice"
+                      message:
+                        type: string
+                        description: The actual message text to display.
+                        example: "This item is currently out of stock and will ship when available."
+                      is_default:
+                        type: boolean
+                        description: Whether this is the default message.
+                        example: false
+                      created_at:
+                        type: string
+                        format: date-time
+                        description: Timestamp when the message was created.
+                        example: "2025-01-15T10:30:00Z"
+                      updated_at:
+                        type: string
+                        format: date-time
+                        description: Timestamp when the message was last updated.
+                        example: "2025-01-20T14:22:00Z"
     SimpleTransactionResponse:
       type: object
       properties:

reference/settings.v3.yml

@@ -2089,6 +2089,15 @@ components:
           description: Describes whether out-of-stock messages are shown on product listing pages.
           default: false
           example: true
+        backorder_availability_prompt:
+          type: string
+          description: Message that appears on the product detail page to reassure shoppers of backorder availability.
+          example: "This item is currently on backorder but will be available soon!"
+        show_backorder_availability_prompt:
+          type: boolean
+          description: Whether or not to show the backorder availability prompt on product detail pages.
+          default: false
+          example: true
     Locale:
       description: 'The basic locale settings for a store, used to give shopper information about languages, countries, etc.'
       type: object