Submit Orders

POST 
/V1/submit

Submits an order to Bonsai for processing. Be careful as these orders will be processed unless Bonsai gets contacted to cancel! - To submit orders in Test Mode, please read our Test Orders Guide

Request

application/json

Body

required

customer objectrequired

email emailrequired

Customer email address. We will be using this email to update the customer about their order

first_name stringrequired

Customer first name.

last_name stringrequired

Customer last name.

products object[]required
Possible values: >= 1
Array [
public_id stringrequired
ID of the product
variant_id stringrequired
ID of the product variant.
quantity floatrequired
Possible values: >= 1
Quantity of the product variant in the cart
]
shipping_address objectrequired

first_name stringrequired

Customer first name.

last_name stringrequired

Customer last name.

address1 stringrequired

The street address of the shipping address.

address2 stringnullable

An optional additional field for the street address of the shipping address.

city stringrequired

The city, town, or village of the shipping address.

country stringrequired

The two-letter code (ISO 3166-1 format) for the country of the shipping address.

name string

Full name.

province stringnullable

The two-letter abbreviation of the region of the shipping address.

phone string

The phone number at the shipping address.

zip stringrequired

The postal code (zip, postcode, Eircode, …) of the shipping address.

payment objectrequired

Payment information for an order

method stringrequired

Possible values: [credit card, external payment, stripe]

Payment method used to pay for the order.

token stringrequired

Payment token for the order. Each payment token may be used for 1 order.

currency string

Possible values: [CAD, USD, GBP, AUD, EUR]

ISO currency code for the currency that customer payment was taken in.

amounts object

Amounts for the order. Required only for external payment method.

shipping floatrequired

Total amount of shipping costs, in target currency (ex. USD).;

taxes floatrequired

The amount of taxes to be paid, in target currency (ex. USD).

goods floatrequired

The amount of goods to be paid, in target currency (ex. USD).

external_order_id string

ID of the order provided to Bonsai by the party who placed the order. This can be anything you like, but should be unique per order.

misc object
Miscellaneous data for the order. For example, analytics data.
data objectrequired
cart_id string

Unique identifier for the cart

note string

Note containing extra information for our team

Responses

200

Success

application/json

Schema

Schema

data object

email email

Email of the customer

shipping_address object

first_name stringrequired

Customer first name.

last_name stringrequired

Customer last name.

address1 stringrequired

The street address of the shipping address.

address2 stringnullable

An optional additional field for the street address of the shipping address.

city stringrequired

The city, town, or village of the shipping address.

country stringrequired

The two-letter code (ISO 3166-1 format) for the country of the shipping address.

name string

Full name.

province stringnullable

The two-letter abbreviation of the region of the shipping address.

phone string

The phone number at the shipping address.

zip stringrequired

The postal code (zip, postcode, Eircode, …) of the shipping address.

shipping_lines object[]

Array [

title stringrequired

The title of the shipping method.

code stringrequired

A reference to the shipping method.

price floatrequired

The price of this shipping method in the shop currency. Can not be negative.

source stringrequired

The source of the shipping method.

tax floatnullable

Taxes for a specific shipping line.

]

line_items object[]

Array [

name stringrequired

The title of the product.

product_id stringrequired

Unique product identifier.

variant_sku stringnullable

variant sku.

variant_id stringrequired

The ID of the product variant.

public_id stringrequired

Public id of product. These will be the public ids of products requested when placing the order.

price floatrequired

The price of the item before discounts have been applied in the shop currency.

quantity floatrequired

The number of items that were purchased.

requires_shipping booleanrequired

Indicate whether product requires shipping.

properties object

name string

Name of product property.

value string

Value of product property.

]

total_tax float

Total amount of taxes to be paid.

total_duties float

Total amount of duties to be paid.

total_price float

Total amount for entire order.

public_id stringrequired

Public id of customer order.

partner_id string

This is the public ID of the partner that the sale will be attributed to.

orderNumber floatrequired

Order number in the system

stripeClientSecrets string[]

payment_description stringnullablerequired

Customer payment method details. This detail can be shown to the customer.

note string

Note containing extra information for our team

Example (from schema)

{
  "data": {
    "email": "qa@shopbonsai.ca",
    "shipping_address": {
      "first_name": "Eddy",
      "last_name": "Bonsai",
      "address1": "351 E 103rd St",
      "address2": "Whitecastle",
      "city": "New York",
      "country": "US",
      "name": "Eddy Bonsai",
      "province": "NY",
      "phone": "555-625-1199",
      "zip": "10029"
    },
    "shipping_lines": [
      {
        "title": "Small Packet International Air",
        "code": "INT.TP",
        "price": 20,
        "source": "canada_post",
        "tax": 12.45
      }
    ],
    "line_items": [
      {
        "name": "Nike Air Jordan",
        "product_id": "7513594",
        "variant_sku": "7513594",
        "variant_id": "4264112",
        "public_id": "cjld2cyuq0000t3rmniod1foy",
        "price": 10,
        "quantity": 1,
        "requires_shipping": true,
        "properties": {
          "name": "custom engraving",
          "value": "Happy Birthday Mom!"
        }
      }
    ],
    "total_tax": 12.25,
    "total_duties": 20.12,
    "total_price": 120.25,
    "public_id": "cjld2cyuq0000t3rmniod1foy",
    "partner_id": "ck865cyk00000xlzo0ftpawme",
    "orderNumber": 54663,
    "stripeClientSecrets": [
      "pi_1DoS1i2eZvKYlo2CXgQLdndX_secret_jYJLrdftGY4odNdK6RIJzMeXO"
    ],
    "payment_description": "visa ending in 4242",
    "note": "Fulfil only if white colour was selected. Or reach out to our support"
  }
}

400

400 - Bad request

application/json

Schema

Schema

errors object[]
Array [
id stringrequired
Unique identifier for error. Can be used for tracing across services.
status floatrequired
HTTP status code.
code stringrequired
Unique code for specific error.
title stringrequired
Short description what the error entails.
detail objectrequired
Useful details related to the error
publicId string
variantId string
]

Example (from schema)

{
  "errors": [
    {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "status": 400,
      "code": "OUT_OF_STOCK",
      "title": "The product is out of stock",
      "detail": {
        "publicId": "clad6pg5z00ru012gfz7hfm92",
        "variantId": "M00679529706740"
      }
    }
  ]
}

401

401 - Unauthorized

application/json

Schema

Schema

errors object[]
Array [
status floatrequired
detail stringnullablerequired
title stringrequired
]

Example (from schema)

{
  "errors": [
    {
      "status": 401,
      "detail": "",
      "title": "Authentication information is missing or invalid"
    }
  ]
}

402

402 - Payment required

application/json

Schema

Schema

errors object[]
Array [
id stringrequired
Unique identifier for error. Can be used for tracing across services.
status floatrequired
HTTP status code.
code stringrequired
Unique code for specific error.
title stringrequired
Short description what the error entails.
detail objectrequired
Useful details related to the error
message string
]

Example (from schema)

{
  "errors": [
    {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "status": 402,
      "code": "PAYMENT_REQUIRED",
      "title": "Payment is required for this order",
      "detail": {
        "message": "Your card was declined."
      }
    }
  ]
}

404

404 - Not found

application/json

Schema

Schema

errors object[]
Array [
id stringrequired
Unique identifier for error. Can be used for tracing across services.
status floatrequired
HTTP status code.
code stringrequired
Unique code for specific error.
title stringrequired
Short description what the error entails.
detail objectrequired
Useful details related to the error
publicId string
variantId string
]

Example (from schema)

{
  "errors": [
    {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "status": 404,
      "code": "VARIANT_DOES_NOT_EXIST",
      "title": "Variant does not exist",
      "detail": {
        "publicId": "clad6pg5z00ru012gfz7hfm92",
        "variantId": "M00679529706740"
      }
    }
  ]
}

500

500 - Internal server error

application/json

Schema

Schema

errors object[]
Array [
id stringrequired
Unique identifier for error. Can be used for tracing across services.
status floatrequired
HTTP status code.
code stringrequired
Unique code for specific error.
title stringrequired
Short description what the error entails.
detail objectrequired
Useful details related to the error
stripeToken string
customer object
email string
first_name string
last_name string
message string
]

Example (from schema)

{
  "errors": [
    {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "status": 500,
      "code": "STRIPE_ERROR",
      "title": "Error during a Stripe operation",
      "detail": {
        "stripeToken": "tok_1EJ2Zp2eZvKYlo2Cg2g2g2g2",
        "customer": {
          "email": "qa@shopbonsai.ca",
          "first_name": "Eddy",
          "last_name": "Bonsai"
        },
        "message": "Your card was declined."
      }
    }
  ]
}

5XX

500 - Unknown error

application/json

Schema

Schema

errors object[]
Array [
status floatrequired
detail stringnullablerequired
title stringrequired
]

Example (from schema)

{
  "errors": [
    {
      "status": 500,
      "detail": "",
      "title": "Unknown error"
    }
  ]
}

Loading...