The payment method request for a cart. If the token is provided no card data is required.
token
string
token
string
Payment Token generated on a specific payment provider. When a token is provided, payment_provider must also be specified in the request.
intent_based_capture
boolean
intent_based_capture
boolean
Trigger payment intent based capture
payment_provider
string
payment_provider
string
Payment provider that this payment method was created on, if any.
ip_v4
string
ip_v4
string
IP address of the device from which this Payment Method originates.
type
enum<string>
type
enum<string>
Type of the payment method being passed in.
card_number
string
card_number
string
Number on the credit or debit card.
card_cvc
integer
card_cvc
integer
CVC code on the credit or debit card.
card_exp_month
integer
card_exp_month
integer
Expiration month of the credit or debit card.
card_exp_year
integer
card_exp_year
integer
Expiration year of the credit or debit card.
card_postal_code
string
card_postal_code
string
Postal Code of the credit or debit card.
complete_checkout
boolean
complete_checkout
boolean
Submit cart immediately after applying the payment method. Cannot be combined with intent_based_checkout.
app_order_id
string
app_order_id
string
Map the order in Violet to an order record within your system.
Set the payment method for your customer. In this example, we have used a sample credit card available through https://stripe.com/docs/testing.
Note: Setting complete_checkout: true will submit the cart immediately. Though it is often best to let the customer confirm and review all their info, then Submit it with the Submit Cart endpoint.
Headers
X-Violet-Token
string
X-Violet-App-Secret
string
X-Violet-App-Id
integer
Path Parameters
cart_id
integer
required
Query Parameters
price_cart
boolean
default: false
Body
application/json
token
string
Payment Token generated on a specific payment provider. When a token is provided, payment_provider must also be specified in the request.
intent_based_capture
boolean
Trigger payment intent based capture
payment_provider
string
Payment provider that this payment method was created on, if any.
ip_v4
string
IP address of the device from which this Payment Method originates.
type
enum<string>
Type of the payment method being passed in.
Available options:
SINGLE_USE_CARD_TOKEN,
MULTI_USE_CARD_TOKEN,
BANK_TOKEN
card_number
string
Number on the credit or debit card.
card_cvc
integer
CVC code on the credit or debit card.
card_exp_month
integer
Expiration month of the credit or debit card.
card_exp_year
integer
Expiration year of the credit or debit card.
card_postal_code
string
Postal Code of the credit or debit card.
complete_checkout
boolean
Submit cart immediately after applying the payment method. Cannot be combined with intent_based_checkout.
app_order_id
string
Map the order in Violet to an order record within your system.
Response
default - application/json
id
integer
token
string
errors
object[]
Errors on the Order. During checkout, if there was an error or issue on one of the order's bags, there will be an error added to this list describing the issue. The checkout API will return 200 with the order object in the response even if there was an issue with a bag so you must always check the response for errors in this list to know if there was an issue on the order.
errors.id
integer
errors.order_id
integer
Order ID
errors.bag_id
integer
Bag ID
errors.entity_id
string
Entity ID
errors.type
enum<string>
Error Type
Available options:
EXTERNAL_CREATE_CART,
EXTERNAL_ADD_ITEM,
EXTERNAL_UPDATE_ITEM,
EXTERNAL_REMOVE_ITEM,
EXTERNAL_ADD_CUSTOMER,
EXTERNAL_ADD_ADDRESSES,
EXTERNAL_ADD_SHIPPING_ADDRESS,
EXTERNAL_ADD_BILLING_ADDRESS,
EXTERNAL_GET_SHIPPING_METHODS,
EXTERNAL_SET_SHIPPING_METHOD,
EXTERNAL_SET_PAYMENT_METHOD,
EXTERNAL_PRICE_CART,
EXTERNAL_SUBMIT_CART,
INTERNAL_ADD_ITEM,
EXTERNAL_DELETE_CART,
EXTERNAL_CANCEL_ORDER,
EXTERNAL_WRITE_ORDER,
EXTERNAL_MARK_ORDER_AS_PAID,
EXTERNAL_ADD_DISCOUNT_CODE,
EXTERNAL_REMOVE_DISCOUNT_CODE,
EXTERNAL_DELETE_ORDER,
EXTERNAL_REFUND_ORDER
errors.message
string
Error Message
errors.date_created
string
Date of creation
errors.platform
enum<string>
Available options:
OTHER,
SHOPIFY,
MAGENTO,
MAGENTO_ONE,
WOOCOMMERCE,
BIGCOMMERCE,
LIGHTSPEED,
ECWID,
YAAS,
SPREECOMMERCE,
DEMANDWARE,
VOLUSION,
PRESTASHOP,
THREEDCART,
SYLIUS,
WIX,
SWELL,
MIVA,
WEBSPHERE,
ORACLECC,
SAPCC,
SQUARESPACE,
SHOPWARE,
COMMERCETOOLS,
MEDUSA,
ABICART,
SPRYKER,
MYSTORE,
CENTRA,
XCART,
VTEX,
KIBO,
SALEOR,
VENDO,
CHORD,
DIGITALRIVER,
SQUARE,
AMAZON,
BIGCARTEL,
CUSTOM
user_id
integer
ID of the User placing the order
app_id
integer
ID of the App creating the order
developer_id
integer
ID of the Developer who placed
customer
object
The Customer Placing the Order
customer.user_id
integer
ID of the User the Order Customer references
customer.first_name
string
required
First Name
customer.last_name
string
required
Last Name
customer.email
string
Email Address of Customer
customer.external_id
string
ID of the Customer on the External Platform
customer.shipping_address
object
The shipping or billing address of a user placing an order
customer.shipping_address.name
string
Name on Address
customer.shipping_address.city
string
required
City
customer.shipping_address.state
string
required
State Abbreviation
customer.shipping_address.country
string
required
Country ISO2 Code
customer.shipping_address.postal_code
string
required
Postal/Zip Code
customer.shipping_address.phone
string
Phone Number
customer.shipping_address.type
enum<string>
required
Address Type
Available options:
SHIPPING,
BILLING
customer.shipping_address.email
string
Email Address
customer.shipping_address.address_1
string
required
First line of the Address
customer.shipping_address.address_2
string
Second line of the Address
customer.shipping_address.first_name
string
customer.shipping_address.last_name
string
customer.billing_address
object
The shipping or billing address of a user placing an order
customer.billing_address.name
string
Name on Address
customer.billing_address.city
string
required
City
customer.billing_address.state
string
required
State Abbreviation
customer.billing_address.country
string
required
Country ISO2 Code
customer.billing_address.postal_code
string
required
Postal/Zip Code
customer.billing_address.phone
string
Phone Number
customer.billing_address.type
enum<string>
required
Address Type
Available options:
SHIPPING,
BILLING
customer.billing_address.email
string
Email Address
customer.billing_address.address_1
string
required
First line of the Address
customer.billing_address.address_2
string
Second line of the Address
customer.billing_address.first_name
string
customer.billing_address.last_name
string
customer.same_address
boolean
Use Same Address for Both
customer.name
string
bags
object[]
Bags in the Order
bags.id
integer
bags.order_id
integer
required
ID of the Order the Bag belongs to
bags.merchant_id
integer
required
ID of the Merchant the Bag references
bags.app_id
integer
required
ID of the App creating this Bag
bags.external_id
string
ID of the Order on the External Ecommerce Platform
bags.status
enum<string>
Status
Available options:
IN_PROGRESS,
SUBMITTED,
ACCEPTED,
COMPLETED,
PARTIALLY_REFUNDED,
REFUNDED,
REJECTED,
CANCELED,
BACKORDERED
bags.fulfillment_status
enum<string>
Fulfillment Status
Available options:
PROCESSING,
SHIPPED,
PARTIALLY_SHIPPED,
DELIVERED,
COULD_NOT_DELIVER,
RETURNED
bags.financial_status
enum<string>
Financial Status
Available options:
UNPAID,
AUTHORIZED,
PENDING,
PAID,
PARTIALLY_PAID,
REFUNDED,
PARTIALLY_REFUNDED,
VOIDED
bags.skus
object[]
SKUs added to the bag
bags.skus.id
integer
bags.skus.merchant_id
integer
ID of the Merchant the SKU belongs to
bags.skus.app_id
integer
ID of the App creating the Order
bags.skus.product_id
string
ID of the Product
bags.skus.sku_id
integer
required
ID of the referenced SKU
bags.skus.external_id
string
ID of the SKU on the External Ecommerce Platform
bags.skus.name
string
Name of the SKU
bags.skus.brand
string
Brand Name
bags.skus.thumbnail
string
URL of the thumbnail image. Useful for order overview displays
bags.skus.quantity
integer
Quantity of the SKU being purchased. Quantities over 1000 will default to 1000
bags.skus.price
integer
Price of the individual SKU. In Cents
bags.skus.weight
number
Weight of SKU
bags.skus.height
number
Height of SKU
bags.skus.width
number
Width of SKU
bags.skus.length
number
Length of SKU
bags.skus.available
boolean
Is the product still available for purchase. If a SKU becomes unavailable it likely means that the product became out of stock after it was added to the cart. Unavailable SKUs cannot be purchased.
bags.skus.status
enum<string>
Sku Status
Available options:
IN_PROGRESS,
PROCESSING,
SHIPPED,
PARTIALLY_SHIPPED,
DELIVERED,
COULD_NOT_DELIVER,
RETURNED,
CANCELED,
REFUNDED,
ERROR,
PARTIALLY_RETURNED,
PARTIALLY_REFUNDED
bags.skus.product_type
enum<string>
Product Type
Available options:
PHYSICAL,
DIGITAL,
VIRTUAL,
BUNDLED
bags.skus.custom
boolean
Is the Sku custom. True when the price has been overridden.
bags.skus.custom_properties
array | null
Used to provide the merchant with custom values for the product. This functionality is currently limited to Shopify merchants.
bags.skus.custom_properties.name
string
required
Name of the custom property.
bags.skus.custom_properties.value
string
required
Value of the custom property.
bags.skus.quantity_fulfilled
integer
The quantity of this item that has been fulfilled
bags.skus.order_sku_rates
object[]
bags.skus.order_sku_rates.order_sku_id
integer
required
ID of the Order SKU the Rate belongs to
bags.skus.order_sku_rates.amount
integer
required
Total Tax amount on Bag. In Cents
bags.skus.order_sku_rates.rate
number
Rate
bags.skus.order_sku_rates.type
enum<string>
required
Rate Type
Available options:
TAX,
SHIPPING,
FEE,
DUTY
bags.skus.order_sku_rates.name
string
required
Rate Name
bags.skus.order_sku_rates.decimal_rate
number
bags.skus.order_sku_rates.dollar_amount
number
bags.skus.line_price
integer
Price of the SKU multiplied by the Quantity. In Cents
bags.shipping_method
object
required
Shipping Methods belonging to an Order
bags.shipping_method.type
enum<string>
Type of Shipping Method
Available options:
CALCULATED,
FLAT_RATE_PRICE,
FLAT_RATE_WEIGHT
bags.shipping_method.Carrier
enum<string>
Available options:
OTHER,
UPS,
USPS,
FEDEX,
DHL,
ONTRAC,
ROYAL_MAIL,
SENDLE,
POSTNORD
bags.shipping_method.label
string
Shipping Method Label
bags.shipping_method.price
integer
required
Total cost of the Shipping Method. In Cents
bags.shipping_method.custom
boolean
Is the shipping method custom. True when the price has been overridden.
bags.shipping_method.min_subtotal
integer
Minimum Subtotal. In Cents. Only applies to Flat Rate by Price
bags.shipping_method.max_subtotal
integer
Maximum Subtotal. In Cents. Only applies to Flat Rate by Price
bags.shipping_method.min_weight
number
Minimum Weight. In Cents. Only applies to Flat Rate by Weight
bags.shipping_method.max_weight
number
Maximum Weight. In Cents. Only applies to Flat Rate by Weight
bags.shipping_method.external_id
string
ID(s) on external ecommerce platform
bags.shipping_method.id
integer
bags.shipping_method.shipping_method_id
string
required
ID of the referenced Shipping Method
bags.shipping_method.bag_id
integer
required
ID of the Bag the Shipping Method applies to
bags.shipping_method.merchant_id
integer
required
ID of the merchant the bag belongs to
bags.shipping_method.tracking_number
string
Carrier Tracking Number
bags.taxes
object[]
required
Taxes applied to the bag
bags.taxes.order_id
integer
required
ID of the Order the Tax belongs to
bags.taxes.merchant_id
integer
required
ID of the Merchant the Bag belongs to
bags.taxes.skus
string[]
SKUs covered by the Tax
bags.taxes.state
string
required
State abbreviation
bags.taxes.postal_code
string
Postal/Zip Code
bags.taxes.rate
number
required
Tax Rate
bags.taxes.amount
integer
required
Total Tax amount on Bag. In Cents
bags.taxes.description
string
Description of the Tax
bags.sub_total
integer
The price of the Bag in the base currency before discounts, shipping, duties, taxes, and tips. In Cents
bags.shipping_total
integer
The sum of all shipping methods applied to the Bag in the base currency. In Cents
bags.tax_total
integer
The sum of all the taxes applied to the Bag in the base currency. In Cents
bags.discount_total
integer
The total discounts applied to the price of the Bag in the base currency. In Cents
bags.total
integer
The sum of all item prices, discounts, shipping, and taxes applied to the Bag in the base currency. In Cents
Exchange rate of currency and external currency, if different, at the time the bag was last priced.
bags.channel
enum<string>
The channel that originated this order.
Available options:
APP,
MARKETPLACE,
FACEBOOK,
INSTAGRAM,
WALMART,
GOOGLE,
TIKTOK,
SNAPCHAT,
PINTEREST
bags.app_order_id
string
App Order ID. Automatically obtained through the app_order_id applied to the order.
bags.platform
enum<string>
The commerce platform used by this merchant.
Available options:
OTHER,
SHOPIFY,
MAGENTO,
MAGENTO_ONE,
WOOCOMMERCE,
BIGCOMMERCE,
LIGHTSPEED,
ECWID,
YAAS,
SPREECOMMERCE,
DEMANDWARE,
VOLUSION,
PRESTASHOP,
THREEDCART,
SYLIUS,
WIX,
SWELL,
MIVA,
WEBSPHERE,
ORACLECC,
SAPCC,
SQUARESPACE,
SHOPWARE,
COMMERCETOOLS,
MEDUSA,
ABICART,
SPRYKER,
MYSTORE,
CENTRA,
XCART,
VTEX,
KIBO,
SALEOR,
VENDO,
CHORD,
DIGITALRIVER,
SQUARE,
AMAZON,
BIGCARTEL,
CUSTOM
bags.fulfillments
object[]
bags.fulfillments.id
integer
bags.fulfillments.bag_id
integer
ID of the bag the fulfillment belongs to.
bags.fulfillments.external_id
string
ID of the fulfillment on the external commerce platform.
bags.fulfillments.carrier
enum<string>
Carrier responsible for the fulfillment. Will be OTHER if raw carrier is not recognized.
Available options:
OTHER,
UPS,
USPS,
FEDEX,
DHL,
ONTRAC,
ROYAL_MAIL,
SENDLE,
POSTNORD
bags.fulfillments.raw_carrier
string
Raw name of carrier from the external commerce platform.
bags.fulfillments.status
enum<string>
ID of the Bag the fulfillment belongs to.
Available options:
PENDING,
PROCESSING,
SUCCESS,
CANCELED,
ERROR,
FAILURE,
NONE_PROVIDED
bags.fulfillments.carrier_status
enum<string>
ID of the Bag the fulfillment belongs to.
Available options:
PENDING,
LABEL_PURCHASED,
LABEL_PRINTED,
CONFIRMED,
READY_FOR_PICKUP,
IN_TRANSIT,
OUT_FOR_DELIVERY,
ATTEMPTED_DELIVERY,
DELIVERED,
FAILURE,
NONE_PROVIDED
bags.fulfillments.tracking_number
string
Tracking number provider by the carrier.
bags.fulfillments.tracking_url
string
Tracking URL provider by the carrier.
bags.fulfillments.skus
object[]
SKUs fulfilled by this fulfillment.
bags.fulfillments.skus.id
integer
bags.fulfillments.skus.fulfillment_id
integer
ID of the fulfillment that contains this item.
bags.fulfillments.skus.order_sku_id
integer
ID of the SKU in the Bag.
bags.fulfillments.skus.quantity_fulfilled
integer
Quantity of the this item fulfilled by this fulfillment.
bags.discounts
object[]
bags.discounts.id
integer
bags.discounts.bag_id
integer
ID of the Bag this discount belong to
bags.discounts.status
enum<string>
Status of discount
Available options:
PENDING,
APPLIED,
INVALID,
NOT_SUPPORTED,
ERROR,
EXPIRED
bags.discounts.type
enum<string>
Type of discount
Available options:
CODE
bags.discounts.value_type
enum<string>
Value type of discount
Available options:
AMOUNT,
PERCENTAGE
bags.discounts.target_type
enum<string>
Target type of the discount
Available options:
ORDER,
SKU,
SHIPPING
bags.discounts.code
string
Code of discount
bags.discounts.external_id
string
External ID of discount
bags.discounts.amount
integer
Amount of discount
bags.discounts.percentage
number
Percentage of discount
bags.discounts.amount_total
integer
Total amount of discount applied to bag
bags.discounts.date_created
string
Date of creation
bags.discounts.date_last_modified
string
Date of last bag discount update
bags.discounts.email
string
Customer email address, possibly necessary for once-per-customer discounts.
bags.wallet_based_checkout
boolean
Is this bag going to be placed through wallet-based checkout
bags.app_name
string
Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.
bags.bag_id
integer
bags.bag_status
enum<string>
Available options:
IN_PROGRESS,
SUBMITTED,
ACCEPTED,
COMPLETED,
PARTIALLY_REFUNDED,
REFUNDED,
REJECTED,
CANCELED,
BACKORDERED
bags.merchant_name
string
Name of Merchant
shipping_address
object
The shipping or billing address of a user placing an order
shipping_address.name
string
Name on Address
shipping_address.city
string
required
City
shipping_address.state
string
required
State Abbreviation
shipping_address.country
string
required
Country ISO2 Code
shipping_address.postal_code
string
required
Postal/Zip Code
shipping_address.phone
string
Phone Number
shipping_address.type
enum<string>
required
Address Type
Available options:
SHIPPING,
BILLING
shipping_address.email
string
Email Address
shipping_address.address_1
string
required
First line of the Address
shipping_address.address_2
string
Second line of the Address
shipping_address.first_name
string
shipping_address.last_name
string
billing_address
object
The shipping or billing address of a user placing an order
billing_address.name
string
Name on Address
billing_address.city
string
required
City
billing_address.state
string
required
State Abbreviation
billing_address.country
string
required
Country ISO2 Code
billing_address.postal_code
string
required
Postal/Zip Code
billing_address.phone
string
Phone Number
billing_address.type
enum<string>
required
Address Type
Available options:
SHIPPING,
BILLING
billing_address.email
string
Email Address
billing_address.address_1
string
required
First line of the Address
billing_address.address_2
string
Second line of the Address
billing_address.first_name
string
billing_address.last_name
string
payment_method
object
Payment Method belonging to an Order
payment_method.brand
string
Brand of Card
payment_method.last_four
string
Last Four Numbers on Card
payment_method.exp_month
integer
Card Expiration Month
payment_method.exp_year
integer
Card Expiration Year
payment_method.cardholder_name
string
Name as it appears on Card
payment_method.payment_method_id
integer
required
ID of the referenced Payment Method
payment_method.default
boolean
Is Default Method
sub_total
integer
The price of the Order in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.
shipping_total
integer
The sum of all shipping methods applied to the Order in the base currency. In Cents.
tax_total
integer
The sum of all the taxes applied to the Order in the base currency. In Cents.
discount_total
integer
The total discounts applied to the price of the Order in the base currency. In Cents.
total
integer
The sum of all item prices, discounts, shipping, and taxes applied to the Order in the base currency. In Cents.
app_customer_id
string
App Customer ID. This should be used to map the order to the ID of the customer in your application.
app_order_id
string
App Order ID. This should be set to a unique identifier in your system. While not enforced unique in Violet's system, it is strongly recommended that unique values are used for each cart to help correlate identifiers between Violet's system and yours.
status
enum<string>
required
Status of the Order
Available options:
IN_PROGRESS,
PROCESSING,
COMPLETED,
CANCELED,
PARTIALLY_REFUNDED,
REFUNDED,
REQUIRES_ACTION
is_guest
boolean
Order is Guest
date_created
string
Date of order creation
date_last_modified
string
Date of last order update
priced
boolean
Is the cart priced
wallet_based_checkout
boolean
Is this cart going to be placed through wallet-based checkout
currency
string
Base currency of cart
referral_id
string
Optional value used to represent an identifier in your system. This value is not required to represent a referral. It can represent the ID of anything in your system and can be used to filter order lookup results. Max length of 128 characters.
currency_symbol
string
Symbol representing the desired currency
app_name
string
Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.
stripe_key
string
Stripe publishable key. Use for tokenizing payment methods.
payment_intent_client_secret
string
Payment intent client secret. Use for payment intent based payment capture and external captures
payment_transactions
object[]
Payment Transactions associated to the bags on this Cart
payment_transactions.id
integer
Unique identifier for the object
payment_transactions.order_id
integer
required
Identifier of the Order entity that this payment transaction is associated with
payment_transactions.payment_provider
string
required
Payment Provider that this transaction is executed against. This is the provider that handles payment processing for this transaction.
Identifier of the payment method associated with this payment transaction in the underlying payment provider system.
payment_transactions.payment_intent_client_secret
string
Client secret for the payment intent associated to this payment transaction
payment_transactions.amount
integer
required
Amount of this payment in the fractional currency unit of this transaction (e.g. cents). This is the amount charged to the shopper.
payment_transactions.metadata
object
Metadata from the payment provider associated to this payment transaction
payment_transactions.related_bags
string[]
Identifiers of the Bags in Violet that are associated with this payment transaction. The amount of this payment transaction is directly computed from the total amounts on the related bags.
payment_transactions.related_refunds
string[]
Identifiers of the Refunds in Violet that are associated with this payment transaction. Refund amounts are not reflected in the amount on this payment transaction.
payment_transactions.currency
string
required
Currency that the amount of this payment transaction is reflected in. This is the currency that the payment provider uses to charge the shopper payment method.
payment_transactions.status
enum<string>
Underlying status of the payment in the payment provider system and should be used to determine what action to take next against this payment transaction.
Available options:
PROCESSING,
CAPTURED,
CANCELLED,
FAILED,
BYPASSED,
REQUIRES_ACTION,
REQUIRES_PAYMENT_METHOD,
REQUIRES_AUTHORIZATION,
AUTHORIZED,
REFUNDED,
PARTIALLY_REFUNDED
payment_transactions.errors
object[]
List of errors associated to this payment transaction during processing.. This value will only be populated if there are errors during processing
payment_transactions.errors.id
integer
Unique identifier for the object.
payment_transactions.errors.error_code
integer
Unique error code corresponding to this error.
payment_transactions.errors.error_message
string
required
Error message describing the issue in the underlying system.