Set the payment method for your customer. Violet doesn’t recommend using card numbers directly in API calls, even during testing. For this example, we have instead used a sample card token available through Stripe .
When building out your live integration to Violet, learn about all the payment options available to you here .
The payment method request for a cart. If the token is provided no card data is required.
Payment Token generated on a specific payment provider. When a token is provided, payment_provider must also be specified in the request.
Unique identifier of the Customer in the payment provider that the payment method is associated to. When a customer_id is provided, payment_provider must also be specified in the request.
Trigger payment intent based capture
Payment provider that this payment method was created on, if any.
IP address of the device from which this Payment Method originates.
Type of the payment method being passed in.
Available options:
SINGLE_USE_CARD_TOKEN
,
MULTI_USE_CARD_TOKEN
,
BANK_TOKEN
,
PAYMENT_INTENT
,
VIOLET_PAYMENT_METHOD_ID
Number on the credit or debit card.
CVC code on the credit or debit card.
Expiration month of the credit or debit card.
Expiration year of the credit or debit card.
Postal Code of the credit or debit card.
Submit cart immediately after applying the payment method. Cannot be combined with intent_based_checkout.
Map the order in Violet to an order record within your system.
ID of the Violet cart or order.
An alternative UUID that can be used as an ID to reference the cart or order.
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.
ID of the parent Order this error occurred in.
ID of the parent Bag this error occurred in.
ID of the entity that caused the error. See the entity_type
property to determine which entity this ID is associated with.
Type of entity that caused the error. See the entity_id
property to determine which entity of this type is related to the error.
Available options:
ORDER
,
BAG
,
SKU
Type of error, indicates which action was being taken when the error occurred.
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
A string message providing more details about the error.
Maximum length: 255
Date the error was first created in Violet.
The external commerce platform the error occurred in.
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
ID of the User placing the order
ID of the App responsible for the creation and submission of this Order.
ID of the Developer responsible for the creation and submission of this Order.
Details of the customer placing the order.
Customer's valid email address.
Maximum length: 64
customer. shipping_address
The shipping or billing address of a user placing an order
customer.shipping_address. city
customer.shipping_address. state
State or province abbreviated code.
customer.shipping_address. country
customer.shipping_address. postal_code
Postal or Zip code to be applied to the address. This value is required for all countries that have postal codes. For countries that do not have postal codes, this value is optional.
customer.shipping_address. type
Available options:
SHIPPING
,
BILLING
customer.shipping_address. address_1
First line of the Address
customer.shipping_address. name
customer.shipping_address. phone
Phone number related to the address. Note: Some external commerce platforms require this value. For these platforms Violet will use a fake number if no value is provided to ensure that the order succeeds.
customer.shipping_address. email
customer.shipping_address. address_2
Second line of the address
customer.shipping_address. first_name
customer.shipping_address. last_name
The shipping or billing address of a user placing an order
customer.billing_address. city
customer.billing_address. state
State or province abbreviated code.
customer.billing_address. country
customer.billing_address. postal_code
Postal or Zip code to be applied to the address. This value is required for all countries that have postal codes. For countries that do not have postal codes, this value is optional.
customer.billing_address. type
Available options:
SHIPPING
,
BILLING
customer.billing_address. address_1
First line of the Address
customer.billing_address. name
customer.billing_address. phone
Phone number related to the address. Note: Some external commerce platforms require this value. For these platforms Violet will use a fake number if no value is provided to ensure that the order succeeds.
customer.billing_address. email
customer.billing_address. address_2
Second line of the address
customer.billing_address. first_name
customer.billing_address. last_name
When only one address is provided, should the one address be used for both the shipping and billing addresses.
Full name of the customer.
One or more Bags that make up the Order. Each Bag will contain the Sku's, shipping methods, and totals unique to a merchant. Each merchant in an Order will have their own Bag.
ID of the parent order the Bag is a child of.
ID of the merchant the Bag is related to.
ID of the App responsible for the creation and submission of this Order.
ID of the Order on the external commerce platform. This value will be null
until the Order submitted.
bags. external_reference_id
An alternative vanity or reference ID that the external commerce platform may use for an order. This is typically an ID or number that may be shown to the shopper in communication from the merchant when the true order ID is hidden.
Overall status of the Bag.
Available options:
IN_PROGRESS
,
SUBMITTED
,
ACCEPTED
,
COMPLETED
,
PARTIALLY_REFUNDED
,
REFUNDED
,
REJECTED
,
CANCELED
,
BACKORDERED
Fulfillment status of the Bag.
Available options:
PROCESSING
,
SHIPPED
,
PARTIALLY_SHIPPED
,
DELIVERED
,
COULD_NOT_DELIVER
,
RETURNED
Financial status of the Bag.
Available options:
UNPAID
,
AUTHORIZED
,
PENDING
,
PAID
,
PARTIALLY_PAID
,
REFUNDED
,
PARTIALLY_REFUNDED
,
VOIDED
Dispute status of the Bag.
Available options:
UNDISPUTED
,
IN_DISPUTE
,
DISPUTE_WON
,
DISPUTE_LOST
Sku's (line items) that have been added to the Bag.
ID of the referenced Sku from the Violet catalog.
Unique ID of the Sku in relation to the order.
ID of the parent Offer that this Sku is a child of.
ID of the Merchant this Sku belongs to.
ID of the App responsible for the creation and submission of this Order.
ID of the parent product the offer is a child off.
ID of the SKU on the external commerce platform.
Name of the Sku, as provided by the merchant.
Name of the brand selling this Sku.
URL of the thumbnail image. Useful for order overview displays.
Quantity of the Sku being purchased. Quantities over 1000 will default to 1000.
Required range: x < 1000
Price of the individual SKU, in cents.
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 Sku's cannot be purchased.
Current status of the Sku.
Available options:
IN_PROGRESS
,
PROCESSING
,
SHIPPED
,
PARTIALLY_SHIPPED
,
DELIVERED
,
COULD_NOT_DELIVER
,
RETURNED
,
CANCELED
,
REFUNDED
,
ERROR
,
PARTIALLY_RETURNED
,
PARTIALLY_REFUNDED
Product type that describes the Sku.
Available options:
PHYSICAL
,
DIGITAL
,
VIRTUAL
,
BUNDLED
Is the Sku custom. Is true
when the price has been overridden.
bags.skus. custom_properties
Used to provide the merchant with custom values for the product. This functionality is currently limited to Shopify merchants.
bags.skus.custom_properties. name
Name of the custom property.
Minimum length: 1
bags.skus.custom_properties. value
Value of the custom property.
Minimum length: 1
bags.skus. quantity_fulfilled
The quantity of this item that has been fulfilled by the merchant.
Rates that apply specifically to this Sku such as taxes, fees, or duties.
bags.skus.rates. order_sku_id
ID of the Order SKU the Rate belongs to
Total Tax amount on Bag. In Cents
Available options:
TAX
,
SHIPPING
,
FEE
,
DUTY
bags.skus.rates. decimal_rate
bags.skus.rates. dollar_amount
Price of the Sku multiplied by the quantity, in Cents
Shipping Methods belonging to an Order
bags.shipping_method. price
Total cost of the Shipping Method. In Cents
bags.shipping_method. shipping_method_id
ID of the referenced Shipping Method
bags.shipping_method. bag_id
ID of the Bag the Shipping Method applies to
bags.shipping_method. merchant_id
ID of the merchant the bag belongs to
bags.shipping_method. type
Available options:
CALCULATED
,
FLAT_RATE_PRICE
,
FLAT_RATE_WEIGHT
bags.shipping_method. Carrier
Available options:
OTHER
,
UPS
,
USPS
,
FEDEX
,
DHL
,
ONTRAC
,
ROYAL_MAIL
,
SENDLE
,
POSTNORD
bags.shipping_method. label
bags.shipping_method. custom
Is the shipping method custom. True when the price has been overridden.
bags.shipping_method. min_subtotal
Minimum Subtotal. In Cents. Only applies to Flat Rate by Price
bags.shipping_method. max_subtotal
Maximum Subtotal. In Cents. Only applies to Flat Rate by Price
bags.shipping_method. min_weight
Minimum Weight. In Cents. Only applies to Flat Rate by Weight
bags.shipping_method. max_weight
Maximum Weight. In Cents. Only applies to Flat Rate by Weight
bags.shipping_method. external_id
ID(s) on external ecommerce platform
bags.shipping_method. tracking_number
Carrier Tracking Number. Deprecated: Use fulfillments
on the Bag object instead.
Tax rates applied to the Bag.
ID of the Order the Tax belongs to
ID of the Merchant the Bag belongs to
Total Tax amount on Bag. In Cents
The price of the Bag in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.
The sum of all shipping methods applied to the Bag in the base currency. In Cents
The sum of all the taxes applied to the Bag in the base currency. In Cents
The total discounts applied to the price of the Bag in the base currency. In Cents
The sum of all item prices, discounts, shipping, and taxes applied to the Bag in the base currency. In Cents
Are taxes included in the cart subtotal. When true
the taxes will not be summed separately.
If the Bag is attached to an external cart in the commerce platform.
The rate used to calculate the apps commission rate for the Bag.
Date the Bag was created in Violet.
Date the Bag was last modified in Violet.
bags. date_last_consolidated
Date the Bag was last checked for updates. This is a part of Order Parity and is used to discover missed or unsent webhooks from the external commerce platforms.
Date when the Bag can no longer be refunded.
Base currency of the Bag.
Currency of the equivalent cart on external commerce platform.
bags. currency_exchange_rate
Exchange rate of currency and external currency, if different, at the time the Bag was last priced.
The type of Channel that originated this Bag.
Available options:
APP
,
MARKETPLACE
,
FACEBOOK
,
INSTAGRAM
,
WALMART
,
GOOGLE
,
TIKTOK
,
SNAPCHAT
,
PINTEREST
Optional ID of the Order in the channels system. Automatically obtained through the app_order_id applied to the Order.
Maximum length: 64
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
A list of fulfillments, if any, that have been applied to this Bag.
ID of the bag the fulfillment belongs to.
bags.fulfillments. external_id
ID of the fulfillment on the external commerce platform.
bags.fulfillments. carrier
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
Raw name of carrier from the external commerce platform.
Status of the bag fullfillment.
Available options:
PENDING
,
PROCESSING
,
SUCCESS
,
CANCELED
,
ERROR
,
FAILURE
,
NONE_PROVIDED
bags.fulfillments. carrier_status
Status provided by the carrier.
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
Tracking number provided by the carrier.
bags.fulfillments. tracking_url
Tracking URL provided by the carrier.
SKUs fulfilled by this fulfillment.
bags.fulfillments.skus. id
bags.fulfillments.skus. fulfillment_id
ID of the fulfillment that contains this item.
bags.fulfillments.skus. order_sku_id
ID of the SKU in the Bag.
bags.fulfillments.skus. quantity_fulfilled
Quantity of the this item fulfilled by this fulfillment.
A list of discounts, if any, that have been applied to this Bag.
ID of the Bag this discount belong to
Available options:
PENDING
,
APPLIED
,
INVALID
,
NOT_SUPPORTED
,
ERROR
,
EXPIRED
bags.discounts. value_type
Available options:
AMOUNT
,
PERCENTAGE
bags.discounts. target_type
Target type of the discount
Available options:
ORDER
,
SKU
,
SHIPPING
bags.discounts. external_id
bags.discounts. percentage
bags.discounts. amount_total
Total amount of discount applied to bag
bags.discounts. date_created
bags.discounts. date_last_modified
Date of last bag discount update
Customer email address, possibly necessary for once-per-customer discounts.
bags. wallet_based_checkout
Is this Bag going to be placed through wallet-based checkout.
Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.
Available options:
IN_PROGRESS
,
SUBMITTED
,
ACCEPTED
,
COMPLETED
,
PARTIALLY_REFUNDED
,
REFUNDED
,
REJECTED
,
CANCELED
,
BACKORDERED
Name of the merchant the Bag is related to.
The shipping or billing address of a user placing an order
State or province abbreviated code.
shipping_address. postal_code
Postal or Zip code to be applied to the address. This value is required for all countries that have postal codes. For countries that do not have postal codes, this value is optional.
Available options:
SHIPPING
,
BILLING
shipping_address. address_1
First line of the Address
Phone number related to the address. Note: Some external commerce platforms require this value. For these platforms Violet will use a fake number if no value is provided to ensure that the order succeeds.
shipping_address. address_2
Second line of the address
shipping_address. first_name
shipping_address. last_name
The shipping or billing address of a user placing an order
State or province abbreviated code.
billing_address. postal_code
Postal or Zip code to be applied to the address. This value is required for all countries that have postal codes. For countries that do not have postal codes, this value is optional.
Available options:
SHIPPING
,
BILLING
billing_address. address_1
First line of the Address
Phone number related to the address. Note: Some external commerce platforms require this value. For these platforms Violet will use a fake number if no value is provided to ensure that the order succeeds.
billing_address. address_2
Second line of the address
billing_address. first_name
billing_address. last_name
Payment Method belonging to an Order
payment_method. payment_method_id
ID of the referenced Payment Method
Last Four Numbers on Card
payment_method. cardholder_name
Name as it appears on Card
The price of the Order in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.
The sum of all shipping methods applied to the Order in the base currency. In Cents.
The sum of all the taxes applied to the Order in the base currency. In Cents.
The total discounts applied to the price of the Order in the base currency. In Cents.
The sum of all item prices, discounts, shipping, and taxes applied to the Order in the base currency. In Cents.
App Customer ID. This should be used to map the order to the ID of the customer in your application.
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.
Available options:
IN_PROGRESS
,
PROCESSING
,
COMPLETED
,
CANCELED
,
PARTIALLY_REFUNDED
,
REFUNDED
,
REQUIRES_ACTION
Date of last order update
Is this cart going to be placed through wallet-based checkout
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.
Symbol representing the currency the Order operates in.
Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.
Stripe publishable key. Use for tokenizing payment methods.
payment_intent_client_secret
Payment intent client secret. Use for payment intent based payment capture and external captures
Payment Transactions associated to the bags on this Cart
payment_transactions. order_id
Identifier of the Order entity that this payment transaction is associated with
payment_transactions. payment_provider
Payment Provider that this transaction is executed against. This is the provider that handles payment processing for this transaction.
payment_transactions. payment_provider_transaction_id
Identifier of the payment transaction in the underlying payment provider system.
payment_transactions. amount
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. currency
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.
Unique identifier for the object
payment_transactions. payment_method_id
Identifier of the payment method associated with this payment transaction in Violet.
payment_transactions. payment_provider_payment_method_id
Identifier of the payment method associated with this payment transaction in the underlying payment provider system.
payment_transactions. payment_intent_client_secret
Client secret for the payment intent associated to this payment transaction
payment_transactions. capture_status
Underlying status of the payment capture 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. capture_method
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:
AUTOMATIC
,
CUSTOM
,
EXTERNAL
payment_transactions. transfer_status
Status of the transfer of distributions associated with this payment transaction.
Available options:
SENT
,
REVERSED
,
PARTIALLY_REVERSED
,
PENDING
,
FAILED
,
BYPASSED
payment_transactions. transfer_method
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:
AUTOMATIC
,
CUSTOM
,
EXTERNAL
payment_transactions. metadata
Metadata from the payment provider associated to this payment transaction
payment_transactions.metadata. {key}
Metadata from the payment provider associated to this payment transaction
payment_transactions. related_bags
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
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. errors
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. error_message
Error message describing the issue in the underlying system.
payment_transactions.errors. payment_transaction_id
Identifier of the PaymentTransaction entity that this error is associated with
payment_transactions.errors. id
Unique identifier for the object.
payment_transactions.errors. error_code
Unique error code corresponding to this error.
payment_transactions.errors. resolved
Indicates whether the error has been resolved. Defaults to false.
payment_transactions.errors. date_resolved
Time at which this error was resolved. In ISO-8601 format. By default, this value is null and only applies to
payment_transactions.errors. date_created
Time at which the object was created. In ISO-8601 format.
payment_transactions. date_created
Time at which the object was created. In ISO-8601 format.
payment_transactions. date_last_modified
Time at which the object was last modified. In ISO-8601 format.
payment_transactions. status
Available options:
PROCESSING
,
CAPTURED
,
CANCELLED
,
FAILED
,
BYPASSED
,
REQUIRES_ACTION
,
REQUIRES_PAYMENT_METHOD
,
REQUIRES_AUTHORIZATION
,
AUTHORIZED
,
REFUNDED
,
PARTIALLY_REFUNDED
Available options:
IN_PROGRESS
,
PROCESSING
,
COMPLETED
,
CANCELED
,
PARTIALLY_REFUNDED
,
REFUNDED
,
REQUIRES_ACTION
Boolean indicating if the cart/order will be payed using a payment intent.