---
title: "Add an order offer"
method: POST
path: "/order_offers"
tags: ["Order Offers"]
---

# Add an order offer

`POST /order_offers`

Add new order offer(s) to an existing order. Order offers are the individual line items of an order. The essential components of an Order Offer is: Price, billing schedule and shipment details

## Request body

- object
  - `order_id` integer, required — The Vrio Order ID returned when creating an order.
  - `offers` object[], required — Define the offers and Items to be used on the order. Use an array if adding multiple Item and Offer combinations.
    - `id` string — A unique identifier for the particular offer for the order. This value is generated by you and used to allow orders to have the same offer on an order more than once.
    - `offer_id` integer, required — Offer ID associated with offer.
    - `order_offer_quantity` integer, required — The quantity of the offer.
    - `item_id` integer — Vrio item id to be used with the offer_id. Required for shared offers.
    - `order_offer_price` string — Override the configured offer price with a different price that will be used on the initial charge.
    - `order_offer_shipping` string — Override the configured offer level shipping price with a different price that will be used on the initial charge.
    - `discount_code` string — Discount code to be applied to this offer.
    - `order_offer_item_options` object[] — When an Item has options, or variants, determine which options should be applied. Each option will have a subset option value. Example: size is an option, Small - Medium - Large is the option value. Required for items that have options.
      - `item_option_id` integer, required — The option to be applied to the item.
      - `item_option_value_id` integer, required — The value to be used for the item option ID passed.
    - `override_initial_item_id` integer, nullable — Pass an Item ID that will be used for the initial only, ths order will then use the item_id passed for all subsequent transactions. See here for additional use cases.
    - `override_initial_item_options` object[] — When using an override_initial_item_id and the item has options, or variants, determine which options should be applied. Each option will have a subset option value. Required with override item has options.
      - `item_option_id` integer, required — The option to be applied to the override_initial_item_id.
      - `item_option_value_id` integer, required — The value to be used for the override_initial_item_id.
    - `order_offer_upsell` boolean — Mark true if this order offer should be flagged as an upsell. This is important for reporting.
    - `order_offer_upsell_weight` integer — This can be used to define the order of upsell. Pass 1 for the first upsell, 2 for the second, etc.
    - `parent_order_offer_id` integer — The parent_order_offer_id is referencing the specific order offer that the upsell was derived from. This would be available if an order was created and an offer was added to it, then you wanted to add an offer to it at a later date. Required when passing order_offer_upsell and not passing a parent_offer_id and parent_order_id.
    - `parent_offer_id` integer — The parent_offer_id is what is passed when the parent_order_offer_id is not available. This would commonly be used when you create an order all at one time.. Required when passing order_offer_upsell and not passing a parent_order_offer_id.
    - `parent_order_id` integer — The id of the original order, used to add an order offer as upsell from a different order.. Required when passing order_offer_upsell and not passing a parent_order_offer_id.
    - `status_type_id` null | 7 | 8, nullable — This can be used to define the status of an upsell. If not passed, Vrio will define statuses. Accepted values are : * `7` - Rejected * `8` - Removed
    - `is_gift` boolean — If true, gift logic will apply to this order.
    - `gift_message` string — Message to use for gift communication. Required if is_gift is true.
    - `gift_date` string — Date to send gift communication. Required if is_gift is true.
    - `gift_name` string — Name for the person receiving the gift. Required if is_gift is true.
    - `gift_email` string — Email for the person receiving the gift. Required if is_gift is true.
    - `gift_phone` string — Phone for the person receiving the gift. Required if is_gift is true.

## Response `200`

OK

- object
  - `order_offers` object[]
    - `order_offer_id` integer
    - `connection_order_offer_id` string, nullable
    - `status_type_id` null | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10, nullable — * `1` - Active * `2` - Cancelled * `3` - Complete * `4` - Partial * `5` - Declined * `6` - Archive * `7` - Rejected * `8` - Removed * `9` - Paused * `10` - Expired
    - `linked_status_type_id` null | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10, nullable — * `1` - Active * `2` - Cancelled * `3` - Complete * `4` - Partial * `5` - Declined * `6` - Archive * `7` - Rejected * `8` - Removed * `9` - Paused * `10` - Expired
    - `date_cancel` string, date-time, nullable
    - `date_created` string, date-time, nullable
    - `date_modified` string, date-time, nullable
    - `date_ordered` string, date-time, nullable
    - `date_reactivate` string, date-time, nullable
    - `date_pause` string, date-time, nullable
    - `date_unpause` string, date-time, nullable
    - `is_gift` boolean
    - `is_recurring` boolean
    - `is_test` boolean
    - `offer_id` integer
    - `offer_name` string
    - `order_id` integer
    - `order_offer_price` string
    - `order_offer_quantity` integer
    - `cancel_type_id` integer, nullable
    - `cancel_by` integer, nullable
    - `discount_id` integer, nullable
    - `order_offer_upsell` boolean
    - `parent_order_offer_id` integer, nullable
    - `charge_timeframe_id` integer, nullable
    - `charge_timeframe_name` string, nullable
    - `offer_cycle_multiple_shipments_count` integer
    - `fulfillment_delay_timeframe_id` integer, nullable
    - `total_shipments_count` integer
    - `shipped_shipments_count` integer
    - `current_shipment_prepaid_cycle` integer, nullable
    - `current_shipment_id` integer, nullable
    - `connection_status_type_name` string
    - `last_recurring_date` string, date-time, nullable
    - `last_recurring_amount` string
    - `next_recurring_date` string, date-time, nullable
    - `next_recurring_amount` string
    - `next_recurring_price` string
    - `next_recurring_charge` integer, nullable
    - `next_recurring_last_four` string, nullable
    - `extra_fields` string, nullable
    - `order_offer_notes` string, nullable
    - `order_offer_shipments` object[]
      - `shipment_id` integer
      - `connection_shipment_id` string, nullable
      - `customer_id` integer
      - `order_id` integer
      - `shipment_prepaid_cycle` integer
      - `shipment_status_id` 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 — * `1` - Pending Post * `2` - Pending Tracking * `3` - Cancelled * `4` - Shipped * `5` - Error * `6` - Delivered * `7` - Declined * `8` - Pending Transaction * `9` - Skipped
      - `transaction_charge_id` integer
      - `connection_id` integer, nullable
      - `fulfillment_id` string, nullable
      - `shipment_tracking_id` string, nullable
      - `carrier_id` null | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 9, nullable — * `1` - USPS * `2` - UPS * `3` - FedEx * `4` - DHL eCommerce * `5` - UPS Mail Innovations * `6` - Canada Post * `8` - Australia Post * `9` - Hermes
      - `shipping_profile_id` integer, nullable
      - `date_cancel` string, date-time, nullable
      - `date_scheduled` string, date-time
      - `date_complete` string, date-time, nullable
      - `date_scan` string, date-time, nullable
      - `date_deliver` string, date-time, nullable
      - `date_return` string, date-time, nullable
      - `date_skip` string, date-time, nullable
      - `date_rma` string, date-time, nullable
      - `shipment_rma` string, nullable
      - `cancel_type_id` integer, nullable
      - `skip_type_id` integer, nullable
      - `shipping_reship_type_id` null | 1 | 2 | 3 | 4, nullable — * `1` - Did not receive package * `2` - Damaged Items * `3` - Items Incorrect * `4` - Quantity Incorrect
      - `shipment_parent_type_id` null | 1 | 2 | 3 | 4, nullable — * `1` - Reship * `2` - Reward * `3` - Gift * `4` - Free
      - `date_created` string, date-time
      - `created_by` integer
      - `date_modified` string, date-time
      - `modified_by` integer
      - `shipment_notes` string, nullable
      - `connection_request_text` string, nullable
      - `connection_response_text` string, nullable
      - `shipment_items` object[]
        - `shipment_item_id` integer
        - `quantity` integer
        - `item_id` integer
        - `item_name` string
        - `item_description` string, nullable
        - `item_additional_description` string, nullable
        - `item_image` string, nullable
        - `shipment_item_sku` string, nullable
        - `items_option_variation_id` integer, nullable
    - `order_offer_items` object[]
      - `item_id` integer
      - `item_name` string
      - `item_category_id` integer, nullable
      - `item_description` string, nullable
      - `item_image` string, nullable
      - `item_active` boolean
      - `item_price` string, nullable
      - `item_msrp` string, nullable
      - `item_cost` string, nullable
      - `item_shippable` boolean
      - `item_sku` string, nullable
      - `item_weight` string, nullable
      - `item_upc` string, nullable
      - `item_slug` string, nullable
      - `item_quantity` integer
      - `connection_id` integer, nullable
      - `out_of_stock_block` boolean
      - `item_turnaround_time` integer
      - `item_additional_description` string, nullable
      - `item_ingredients` string, nullable
      - `item_video` string, nullable
      - `item_sales_page` string, nullable
      - `item_perishable` boolean
      - `item_tax_code` string, nullable
      - `item_additional_details_1` string, nullable
      - `item_additional_details_2` string, nullable
      - `item_additional_details_3` string, nullable
      - `item_additional_details_4` string, nullable
      - `item_additional_details_5` string, nullable
      - `date_created` string, date-time
      - `created_by` integer
      - `date_modified` string, date-time
      - `modified_by` integer
      - `item_notes` string, nullable
    - `order_offer_gifts` object[]
      - `order_offer_id` integer
      - `gift_card_code` string, nullable
      - `gift_name` string, nullable
      - `gift_message` string, nullable
      - `gift_email` string, nullable
      - `gift_phone` string, nullable
      - `gift_date` string, date-time, nullable
      - `gift_date_sent` string, date-time, nullable
      - `gift_status` string

## Other responses

- `400` — Error response
- `401` — Unauthorized response
- `403` — Forbidden response
- `500` — Error response

---

[API](https://skmtc.net/vrio/apis/crm-configuration.md) · [All operations](https://skmtc.net/vrio/apis/crm-configuration/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vrio/crm-configuration/versions/62037010356e/schema)