v1

latestOpenAPI 3.0.12026-07-2412502.6 MB

Orders

Add an order

Add a new order. A unique order can have one or multiple Offers, or line items, associated with it. An order can be created and processed or authorized at the same time. When passing an action value, there are more fields that would be required on the order, these fields are tagged with required with action and conditionally required with action When passing an action value, a <code>response_code=100</code> will indicate that the charge has been processed successfully with the gateway and there is no further action required. A <code>response_code=101</code> will indicate that there are more actions that need to be done in order to complete the charge. This is typical when using PayPal, AfterPay, Klarna or when using a 3 step redirect for 3DS transactions. To complete the transaction you will need to use the <code>/order/{order_id}/complete</code> method. Learn more <a href='https://docs.vrio.com/docs/handling-101-response-codes' target='_blank'>here</a>.

post/orders

Request body

action'authorize' | 'process'

Define whether to immediately authorize or process the order. If left blank, a Partial order will be created

connection_idinteger required

Vrio billing connection ID. This is found on the connection page within your Vrio Instance.

campaign_idinteger required

Campaign ID to associate the order to.

emailstring

Email address of the customer. This is what creates a unique customer ID. Note - if using the same email all orders will group to that customer. required when customer_id is empty.

customer_idinteger

A distinct identifier linked to an individual customer. Each customer is assigned a unique Customer ID based on their email. When incorporating a new order for an existing customer, you should provide the associated customer_id. This groups all orders for the same customer. Required when email is empty.

first_namestring

Customer first name. If not passed, the bill_fname value will be used.

last_namestring

Customer last name. If not passed, the bill_lname value will be used.

phonestring

Customer telephone number.

birthdaystring date

Customer birthdate. YYYY-MM-DD

genderstring

Customer gender.

cart_tokenstring

Existing cart token to reference for this order.

create_cartboolean

Create and associate a cart token to this order. Only if no cart token is passed. This is only used when using the <a href='https://vrio.zendesk.com/hc/en-us/articles/14363487186327-Checkout' target='_blank'>Vrio Hosted Checkout</a> configured within the Campaign.

customers_address_billing_idinteger

A billing address is required to process an order. Either passing an an address id or creating a new address with the bill_ fields.

customers_address_shipping_idinteger

A shipping address is required to process an order that has a shippable item. Either passing an an address id or creating a new address with the ship_ fields.

bill_fnamestring

Billing first name. Required when customers_address_billing_id is empty.

bill_lnamestring

Billing last name. Required when customers_address_billing_id is empty.

bill_address1string

Billing address line 1. Required when customers_address_billing_id is empty.

bill_address2string

Billing address line 2

bill_citystring

Billing city. Required when customers_address_billing_id is empty.

bill_countrystring

Billing country code, 2 letters (example : US). Required when customers_address_billing_id is empty.

bill_organizationstring

Billing organization.

bill_statestring

Billing state. Required when customers_address_billing_id is empty and bill_county is US or CA.

bill_zipcodestring

Billing zipcode. Required when customers_address_billing_id is empty

same_addressboolean

Pass as true to use the same address for billing and shipping. Only one of those is required in that case.

ship_fnamestring

Shipping first name. Required when customers_address_shipping_id is empty and order has shippable items.

ship_lnamestring

Shipping last name. Required when customers_address_shipping_id is empty and order has shippable items.

ship_address1string

Shipping address line 1. Required when customers_address_shipping_id is empty and order has shippable items.

ship_address2string

Shipping address line 2

ship_citystring

Shipping city. Required when customers_address_shipping_id is empty and order has shippable items.

ship_countrystring

Shipping country code, 2 letters (example : US). Required when customers_address_shipping_id is empty and order has shippable items.

ship_organizationstring

Shipping organization

ship_statestring

Shipping state. Required when customers_address_shipping_id is empty and order has shippable items and ship_country is US or CA.

ship_zipcodestring

Shipping zipcode. Required when customers_address_shipping_id is empty and order has shippable items.

shipping_profile_idinteger

Shipping profile to be used to determine shipping logic. Required if shipping profiles are setup on the campaign and there are shippable items on the order.

payment_method_id1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11

1 - Credit Card
2 - Check
3 - Google Pay
4 - Apple Pay
5 - Cash
6 - Paypal
7 - Sofort
8 - POLi
9 - SEPA
10 - ACH
11 - Afterpay

merchant_idinteger

Force a specific merchant to use for this order. This will override any campaign payment configuration.

merchant_descriptorstring

Some gateways allow for Vrio to pass the merchant descriptor dynamically when processing a charge. This is configured when setting up the merchant account in Vrio. Override the value on the merchant account by passing this field.

route_idinteger

Force a specific route to use for this order. This will override any campaign payment configuration.

currency_idinteger

Force a specific currency to use for this order. This will override any campaign payment configuration.

order_taxstring

Override the tax applied on that order. This will override any campaign payment configuration.

customer_card_idinteger

A customer card is required when using the CC payment method. Either passing an existing customer card id or using the card_ fields.

card_type_idnull | 1 | 2 | 3 | 4 nullable

Required when passing payment method ID = 1 and when not passing a customer card ID.

1 - Mastercard
2 - Visa
3 - Discover
4 - American Express

card_numberstring

Required when passing payment_method_id = 1 and when not passing a customer_card_id. Must be 15 or 16 digits with no other characters.

card_cvvstring

Required when passing payment_method_id = 1 and when not passing a customer_card_id.

card_exp_monthinteger

Card Expiration month (08). Required when passing payment_method_id = 1 and when not passing a customer_card_id.

card_exp_yearinteger

Card Expiration year (2018). Required when passing payment_method_id = 1 and when not passing a customer_card_id.

check_presentboolean

check_numberstring

Required when passing payment_method_id = 2.

check_amountstring

Required when passing payment_method_id = 2.

bank_account_numberstring

Required when passing payment_method_id = 10.

bank_routing_numberstring

Required when passing payment_method_id = 10.

redirect_urlstring

Redirect url used for 3ds three step process, PayPal, Klarna and Afterpay

payment_tokenstring

Used to process apple pay/google pay or paypal.

apply_customer_balancestring

Apply a customer balance amount to that order.

date_auto_capturestring date-time

Auto capture date (2025-08-17 00:00:00) in EST. For authorizations only.

order_cardholder_authstring[]

3D SECURE ONLY Indicates whether a transaction qualifies as an authenticated transaction or account verification. Array of values (for each transaction cycle). Example : ["Y","Y"]

order_ecistring[]

3D SECURE ONLY E-commerce indicator. Array of values (for each transaction cycle). Example : ["05","05"]

order_cavvstring[]

3D SECURE ONLY Cardholder authentication verification value. Array of values (for each transaction cycle). Example : ["XXkBB3eIFgAAAAnDhAIJdQXXXXX=","XXkBB3eIFgAAAAnDhAIJdQXXXXX="]

order_3ds_versionstring[]

3D SECURE ONLY Version of the 3D Secure that was used when the transaction was already authenticated using an external MPI. For example: 1.0.2 or 2.1.0. Array of values (for each transaction cycle). Example : ["2.1.0","2.1.0"]

order_3ds_ds_transaction_idstring[]

Version 2+ 3D SECURE ONLY Cardholder authentication transaction id. Array of values (for each transaction cycle). Example : ["XXXXXXX-37b6-4ba7-b50b-b4491515eaf4","XXXXXXX-37b6-4ba7-b50b-b4491515eaf4"]

order_xidstring[]

Version 1 3D SECURE ONLY Cardholder authentication transaction id. Array of values (for each transaction cycle)

order_3ds_enrollment_statusstring[]

3D SECURE ONLY Indicates whether a transaction qualifies as a being enrolled for 3DS authentication. Array of values (for each transaction cycle). Example : ["E","E"]

order_3ds_bypass_reattemptboolean[]

3D SECURE ONLY If this flag is passed, 3ds values will not be posted to the gateway for reattempts. Array of values (for each transaction cycle). Example : [0,1]

session_idstring

A custom session id to associate with the order.

ip_addressstring

Customer IP Address at the time of order

tracking1string

Custom Tracking Variable Option 1

tracking2string

Custom Tracking Variable Option 2

tracking3string

Custom Tracking Variable Option 3

tracking4string

Custom Tracking Variable Option 4

tracking5string

Custom Tracking Variable Option 5

tracking6string

Custom Tracking Variable Option 6

tracking7string

Custom Tracking Variable Option 7

tracking8string

Custom Tracking Variable Option 8

tracking9string

Custom Tracking Variable Option 9

tracking10string

Custom Tracking Variable Option 10

tracking11string

Custom Tracking Variable Option 11

tracking12string

Custom Tracking Variable Option 12

tracking13string

Custom Tracking Variable Option 13

tracking14string

Custom Tracking Variable Option 14

tracking15string

Custom Tracking Variable Option 15

tracking16string

Custom Tracking Variable Option 16

tracking17string

Custom Tracking Variable Option 17

tracking18string

Custom Tracking Variable Option 18

tracking19string

Custom Tracking Variable Option 19

tracking20string

Custom Tracking Variable Option 20

referral_tokenstring

Referral token to be appled to this order. This is used when Reward Profiles are applicable.

user_agentstring

User agent string for order.

browser_accept_headerstring

Browser accept header for order.

browser_java_enabledboolean

Java enabled setting for order.

browser_javascript_enabledboolean

Javascript enabled setting for order.

browser_languagestring

Browser language for order.

browser_screen_color_depthstring

Browser screen color depth for order.

browser_screen_sizestring

Browser screen size for order.

browser_timezonestring

Browser timezone for order.

order_notesstring

Apply note to the history of this order

Response

order_idinteger

connection_order_idstring nullable

campaign_idinteger

status_type_idnull | 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

customer_card_idinteger nullable

customer_idinteger

customers_address_billing_idinteger nullable

customers_address_shipping_idinteger nullable

date_createdstring date-time nullable

date_modifiedstring date-time nullable

date_authorizedstring date-time nullable

date_auto_capturestring date-time nullable

date_orderedstring date-time nullable

date_capturestring date-time nullable

is_testboolean

ip_addressstring nullable

order_discountstring

order_pixelboolean

cart_tokenstring nullable

order_pixel_blockstring nullable

order_notesstring nullable

created_byinteger

modified_byinteger

tracking1string nullable

tracking2string nullable

tracking3string nullable

tracking4string nullable

tracking5string nullable

tracking6string nullable

tracking7string nullable

tracking8string nullable

tracking9string nullable

tracking10string nullable

tracking11string nullable

tracking12string nullable

tracking13string nullable

tracking14string nullable

tracking15string nullable

tracking16string nullable

tracking17string nullable

tracking18string nullable

tracking19string nullable

tracking20string nullable

user_agentstring nullable

Example response

{
  "date_created": "2023-04-01 00:00:00",
  "date_modified": "2023-04-01 00:00:00",
  "date_authorized": "2023-04-01 00:00:00",
  "date_auto_capture": "2023-04-01 00:00:00",
  "date_ordered": "2023-04-01 00:00:00",
  "date_capture": "2023-04-01 00:00:00",
  "cart": {
    "campaign": {
      "campaign_checkout_upsell": {
        "items": [
          {
            "date_created": "2023-04-01 00:00:00",
            "date_modified": "2023-04-01 00:00:00"
          }
        ]
      }
    },
    "order": {
      "date_authorized": "2023-04-01 00:00:00",
      "date_ordered": "2023-04-01 00:00:00"
    },
    "offers": [
      {
        "gift_date": "2023-04-01 00:00:00",
        "upsells": [
          {
            "items": [
              {
                "date_created": "2023-04-01 00:00:00",
                "date_modified": "2023-04-01 00:00:00"
              }
            ]
          }
        ]
      }
    ]
  },
  "order_offers": [
    {
      "date_cancel": "2023-04-01 00:00:00",
      "date_created": "2023-04-01 00:00:00",
      "date_modified": "2023-04-01 00:00:00",
      "date_ordered": "2023-04-01 00:00:00",
      "date_reactivate": "2023-04-01 00:00:00",
      "date_pause": "2023-04-01 00:00:00",
      "date_unpause": "2023-04-01 00:00:00",
      "last_recurring_date": "2023-04-01 00:00:00",
      "next_recurring_date": "2023-04-01 00:00:00",
      "order_offer_shipments": [
        {
          "date_cancel": "2023-04-01 00:00:00",
          "date_scheduled": "2023-04-01 00:00:00",
          "date_complete": "2023-04-01 00:00:00",
          "date_scan": "2023-04-01 00:00:00",
          "date_deliver": "2023-04-01 00:00:00",
          "date_return": "2023-04-01 00:00:00",
          "date_skip": "2023-04-01 00:00:00",
          "date_rma": "2023-04-01 00:00:00",
          "date_created": "2023-04-01 00:00:00",
          "date_modified": "2023-04-01 00:00:00"
        }
      ],
      "order_offer_items": [
        {
          "date_created": "2023-04-01 00:00:00",
          "date_modified": "2023-04-01 00:00:00"
        }
      ],
      "order_offer_gifts": [
        {
          "gift_date": "2023-04-01 00:00:00",
          "gift_date_sent": "2023-04-01 00:00:00"
        }
      ]
    }
  ],
  "customer_card": {
    "date_created": "2023-04-01 00:00:00",
    "date_modified": "2023-04-01 00:00:00"
  }
}