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.
Map the order in Violet to an order record within your system.
CVC code on the credit or debit card.
Expiration month of the credit or debit card.
Expiration year of the credit or debit card.
Number on 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.
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
IP address of the device from which this Payment Method originates.
Payment provider that this payment method was created on, if any.
Payment Token generated on a specific payment provider. When a token is provided, payment_provider must also be specified in the request.
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
App Customer ID. This should be used to map the order to the ID of the customer in your application.
ID of the App responsible for the creation and submission of this Order.
Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.
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.
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 App responsible for the creation and submission of this Order.
ID of the merchant the Bag is related to.
ID of the parent order the Bag is a child of.
Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.
Optional ID of the Order in the channels system. Automatically obtained through the app_order_id applied to the Order.
Available options:
IN_PROGRESS,
SUBMITTED,
ACCEPTED,
COMPLETED,
PARTIALLY_REFUNDED,
REFUNDED,
REJECTED,
CANCELED,
BACKORDERED
The type of Channel that originated this Bag.
Available options:
APP,
MARKETPLACE,
FACEBOOK,
INSTAGRAM,
WALMART,
GOOGLE,
TIKTOK,
SNAPCHAT,
PINTEREST
The rate used to calculate the apps commission rate for the Bag.
Base currency of the Bag.
bags. currency_exchange_rate
Exchange rate of currency and external currency, if different, at the time the Bag was last priced.
Date the Bag was created 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 the Bag was last modified in Violet.
The total discounts applied to the price of the Bag in the base currency. In Cents
A list of discounts, if any, that have been applied to this Bag.
bags.discounts. amount_total
Total amount of discount applied to bag
ID of the Bag this discount belong to
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.discounts. external_id
bags.discounts. percentage
Available options:
PENDING,
APPLIED,
INVALID,
NOT_SUPPORTED,
ERROR,
EXPIRED
bags.discounts. target_type
Target type of the discount
Available options:
ORDER,
SKU,
SHIPPING
bags.discounts. value_type
Available options:
AMOUNT,
PERCENTAGE
Dispute status of the Bag.
Available options:
UNDISPUTED,
IN_DISPUTE,
DISPUTE_WON,
DISPUTE_LOST
If the Bag is attached to an external cart in the commerce platform.
Currency of the equivalent cart on external commerce platform.
ID of the Order on the external commerce platform. This value will be null until the Order submitted.
Financial status of the Bag.
Available options:
UNPAID,
AUTHORIZED,
PENDING,
PAID,
PARTIALLY_PAID,
REFUNDED,
PARTIALLY_REFUNDED,
VOIDED
Fulfillment status of the Bag.
Available options:
PROCESSING,
SHIPPED,
PARTIALLY_SHIPPED,
DELIVERED,
COULD_NOT_DELIVER,
RETURNED
A list of fulfillments, if any, that have been applied to this Bag.
ID of the bag the fulfillment belongs to.
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. 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. external_id
ID of the fulfillment on the external commerce platform.
bags.fulfillments. raw_carrier
Raw name of carrier from the external commerce platform.
SKUs fulfilled by this fulfillment.
bags.fulfillments.skus. fulfillment_id
ID of the fulfillment that contains this item.
bags.fulfillments.skus. id
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.
Status of the bag fullfillment.
Available options:
PENDING,
PROCESSING,
SUCCESS,
CANCELED,
ERROR,
FAILURE,
NONE_PROVIDED
bags.fulfillments. tracking_number
Tracking number provided by the carrier.
bags.fulfillments. tracking_url
Tracking URL provided by the carrier.
Name of the merchant the Bag is related to.
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
Date when the Bag can no longer be refunded.
Shipping Methods belonging to an Order
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. price
Total cost of the Shipping Method. In Cents
bags.shipping_method. shipping_method_id
ID of the referenced Shipping Method
bags.shipping_method. Carrier
Available options:
OTHER,
UPS,
USPS,
FEDEX,
DHL,
ONTRAC,
ROYAL_MAIL,
SENDLE,
POSTNORD
bags.shipping_method. custom
Is the shipping method custom. True when the price has been overridden.
bags.shipping_method. external_id
ID(s) on external ecommerce platform
bags.shipping_method. label
bags.shipping_method. max_subtotal
Maximum Subtotal. In Cents. Only applies to Flat Rate by Price
bags.shipping_method. max_weight
Maximum Weight. In Cents. Only applies to Flat Rate by Weight
bags.shipping_method. min_subtotal
Minimum 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. tracking_number
bags.shipping_method. type
Available options:
CALCULATED,
FLAT_RATE_PRICE,
FLAT_RATE_WEIGHT
The sum of all shipping methods applied to the Bag in the base currency. In Cents
Sku's (line items) that have been added to the Bag.
ID of the referenced Sku from the Violet catalog.
ID of the App responsible for the creation and submission of this Order.
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.
Name of the brand selling this Sku.
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
ID of the SKU on the external commerce platform.
Unique ID of the Sku in relation to the order.
Price of the Sku multiplied by the quantity, in Cents
ID of the Merchant this Sku belongs to.
Name of the Sku, as provided by the merchant.
ID of the parent Offer that this Sku is a child of.
Price of the individual SKU, in cents.
ID of the parent product the offer is a child off.
Product type that describes the Sku.
Available options:
PHYSICAL,
DIGITAL,
VIRTUAL,
BUNDLED
Quantity of the Sku being purchased. Quantities over 1000 will default to 1000.
Required range: x < 1000
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.
Total Tax amount on Bag. In Cents
bags.skus.rates. order_sku_id
ID of the Order SKU the Rate belongs to
Available options:
TAX,
SHIPPING,
FEE,
DUTY
bags.skus.rates. decimal_rate
bags.skus.rates. dollar_amount
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
URL of the thumbnail image. Useful for order overview displays.
Overall status of the Bag.
Available options:
IN_PROGRESS,
SUBMITTED,
ACCEPTED,
COMPLETED,
PARTIALLY_REFUNDED,
REFUNDED,
REJECTED,
CANCELED,
BACKORDERED
The price of the Bag in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.
The sum of all the taxes applied to the Bag in the base currency. In Cents
Tax rates applied to the Bag.
Total Tax amount on Bag. In Cents
ID of the Merchant the Bag belongs to
ID of the Order the Tax belongs to
Are taxes included in the cart subtotal. When true the taxes will not be summed separately.
The sum of all item prices, discounts, shipping, and taxes applied to the Bag in the base currency. In Cents
bags. wallet_based_checkout
Is this Bag going to be placed through wallet-based checkout.
The shipping or billing address of a user placing an order
billing_address. address_1
First line of the Address
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.
State or province abbreviated code.
Available options:
SHIPPING,
BILLING
billing_address. address_2
Second line of the address
billing_address. first_name
billing_address. last_name
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.
Symbol representing the currency the Order operates in.
Details of the customer placing the order.
Customer's valid email address.
The shipping or billing address of a user placing an order
customer.billing_address. address_1
First line of the Address
customer.billing_address. city
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. state
State or province abbreviated code.
customer.billing_address. type
Available options:
SHIPPING,
BILLING
customer.billing_address. address_2
Second line of the address
customer.billing_address. email
customer.billing_address. first_name
customer.billing_address. last_name
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.
ID of the Customer on the External Platform
Full name of the customer.
When only one address is provided, should the one address be used for both the shipping and billing addresses.
customer. shipping_address
The shipping or billing address of a user placing an order
customer.shipping_address. address_1
First line of the Address
customer.shipping_address. city
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. state
State or province abbreviated code.
customer.shipping_address. type
Available options:
SHIPPING,
BILLING
customer.shipping_address. address_2
Second line of the address
customer.shipping_address. email
customer.shipping_address. first_name
customer.shipping_address. last_name
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.
Reference ID of the customer placing the order.
Date of last order update
ID of the Developer responsible for the creation and submission of this Order.
The total discounts applied to the price of the Order in the base currency. In Cents.
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 Bag this error occurred in.
Date the error was first created in Violet.
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
A string message providing more details about the error.
Maximum length: 255
ID of the parent Order this error occurred in.
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
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
ID of the Violet cart or order.
Boolean indicating if the cart/order will be payed using a payment intent.
Available options:
IN_PROGRESS,
PROCESSING,
COMPLETED,
CANCELED,
PARTIALLY_REFUNDED,
REFUNDED,
REQUIRES_ACTION
Payment intent client secret. Use for payment intent based payment capture and external captures
Payment Method belonging to an Order
payment_method. payment_method_id
ID of the referenced Payment Method
payment_method. cardholder_name
Name as it appears on Card
Last Four Numbers on Card
Payment Transactions associated to the bags on this Cart
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.
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. 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. 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. 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. 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. date_created
Time at which the object was created. In ISO-8601 format.
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. error_code
Unique error code corresponding to this error.
payment_transactions.errors. id
Unique identifier for the object.
payment_transactions.errors. resolved
Indicates whether the error has been resolved. Defaults to false.
Unique identifier for the object
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. payment_intent_client_secret
Client secret for the payment intent associated to this payment transaction
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. 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. status
Available options:
PROCESSING,
CAPTURED,
CANCELLED,
FAILED,
BYPASSED,
REQUIRES_ACTION,
REQUIRES_PAYMENT_METHOD,
REQUIRES_AUTHORIZATION,
AUTHORIZED,
REFUNDED,
PARTIALLY_REFUNDED
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. transfer_status
Status of the transfer of distributions associated with this payment transaction.
Available options:
SENT,
REVERSED,
PARTIALLY_REVERSED,
PENDING,
FAILED,
BYPASSED
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.
The shipping or billing address of a user placing an order
shipping_address. address_1
First line of the Address
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.
State or province abbreviated code.
Available options:
SHIPPING,
BILLING
shipping_address. address_2
Second line of the address
shipping_address. first_name
shipping_address. last_name
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.
The sum of all shipping methods applied to the Order in the base currency. In Cents.
Available options:
IN_PROGRESS,
PROCESSING,
COMPLETED,
CANCELED,
PARTIALLY_REFUNDED,
REFUNDED,
REQUIRES_ACTION
Stripe publishable key. Use for tokenizing payment methods.
The price of the Order in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.
The sum of all the taxes applied to the Order in the base currency. In Cents.
An alternative UUID that can be used as an ID to reference the cart or order.
The sum of all item prices, discounts, shipping, and taxes applied to the Order in the base currency. In Cents.
ID of the User placing the order
Is this cart going to be placed through wallet-based checkout
