Backend API
Create a new order.
Arguments
ID of the customer's account.
The customer's billing details. Defaults to account.billing. Updating billing will also update the corresponding account billing object.
ID of the customer's credit card on file, if applicable.
Expandable link to the customer's credit card on file, if applicable.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Amazon billing details used when billing.method=amazon.
Amazon access token provided when a customer authorizes payment in a storefront.
Amazon order reference ID created when a customer initiates payment in a storefront.
Credit card billing details used when billing.method=card.
Token generated by Swell Checkout or Stripe.js.
Two-digit number representing the credit card expiration month.
Four-digit number representing the credit card expiration year.
Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Last four digits of the card number.
ID of the payment gateway that should be used to process payments.
Indicates this is a test card.
When used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable, or unchecked.
Billing city/district/suburb/town/village.
Two-letter ISO code country code.
Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.
Billing full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
PayPal billing details used when billing.method=paypal.
PayPal payer ID provided when a customer authorizes payment in a storefront.
PayPal payment ID created when a customer initiates payment in a storefront.
Billing phone number.
Billing state/county/province/region.
Billing zip/postal code.
Indicates billing details represent the customer's default payment method.
Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.
Affirm billing details used when billing.method=affirm.
Token used to communicate payment information to the gateway.
Resolve billing details used when billing.method=resolve.
Charge ID returned by the payment gateway for the payment.
Klarna billing details used when billing.method=klarna.
Payment information returned by the gateway during payment initialization.
Ideal billing details used when billing.method=ideal.
Token used to communicate payment information to the gateway.
Bancontact billing details used when billing.method=bancontact.
Payment information returned by the gateway during payment initialization.
Google Pay billing details used when billing.method=google.
One-time use reference element used to communicate payment information to a payment gateway.
Gateway used to facilitate the transaction. For example, Braintree.
Apple Pay billing details used when billing.method=apple.
One-time use reference element used to communicate payment information to a payment gateway.
Gateway used to facilitate the transaction. For example, Braintree.
Coupon code applied to the order. See coupons for details.
List of line items describing the products ordered.
List of items offered as a bundle. Defaults to product.bundle_items.
ID of the bundle item product.
Expandable link to the bundle item product.
Quantity of the bundle item being ordered. Defaults to 1.
Weight to be used in shipping calculation, if applicable.
Quantity of the bundle item that has been restocked after a return, if applicable.
Quantity of the bundle item that can still be returned after fulfillment, if applicable.
ID of the bundle item variant.
Expandable link to the bundle item product variant.
Unique identifier for the object.
Method of delivery taken automatically from product.delivery.
Possible enum values:
Item options matching one or more of product.options. When adding to the order, you can specify either the option id or name (case-insensitive) to identify the option.
Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID send_email and value as the recipient email address, and send_note as a custom message from the customer to the recipient sent by email.
Unique identifier for the object.
Name of the product option. Populated automatically when adding an option by ID.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.
ID of the associated value.
Indicates the option refers to a variant aspect.
Quantity of the bundle item canceled before fulfillment, if applicable.
Quantity of stock consumed by the bundle item, if applicable.
Quantity of the bundle item that can be fulfilled, if applicable.
Quantity of the bundle item that has been fulfilled, if applicable.
Quantity of the bundle item that can be fulfilled by a gift card. Applies when delivery=giftcard.
Total quantity of bundle items that have been returned.
Quantity of the bundle item that can be fulfilled by a shipment. Applies when delivery=shipment.
Total quantity of the bundle item to be fulfilled, calculated as item.quantity * bundle_item.quantity.
Indicates whether the bundle item has stock tracking enabled.
Quantity of bundle items that are able to be canceled.
Quantity of shipments that have been delivered.
This field is a copy of the item's product.name.
Description used for custom line items, when product is not defined.
List of discounts to apply to the item. Normally populated by applying a coupon or promotions.
Unique identifier for the object. Should refer to one of the IDs in the order discounts object.
Fixed discount amount.
Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API for details.
Item options matching one or more of product.options. When adding to the order, you can specify either the option id or name (case-insensitive) to identify the option.
Gift card products have two special options that can be used when fulfilling gift cards by email. Use the option ID send_email and value as the recipient email address, and send_note as a custom message from the customer to the recipient sent by email.
Unique identifier for the object.
Name of the product option. Populated automatically when adding an option by ID.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.
ID of the associated value.
Indicates the option refers to a variant aspect.
Price of the item. Override this value to set a custom price. Defaults to product price or sale price.
ID of the item product.
Quantity of the item being ordered. Defaults to 1.
Quantity of the item that has been restocked after a return, if applicable.
Quantity of the item that can still be returned after fulfillment, if applicable.
Quantity of the item that has been returned after fulfillment, if applicable.
Weight to be used in shipping calculation, if applicable.
List of tax rules to apply to the item. Normally populated by tax settings.
Unique identifier for the object. Should refer to one of the IDs in the order taxes object.
Fixed tax amount.
ID of the item variant, if applicable.
Unique identifier for the item.
Method of delivery taken automatically from product.delivery.
Possible enum values:
Total discount amount divided by quantity.
Total discount applied to the item.
Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed.
Total price added to sub total by multiplying quantity and price.
Expandable link to the item product.
Name of the product.
Quantity of the item canceled before fulfillment, if applicable.
Quantity of stock consumed by the item, if applicable.
Quantity of the item that can be fulfilled, if applicable.
Quantity of the item that has been fulfilled, if applicable.
Quantity of the item that can be fulfilled by a gift card. Applies when delivery=giftcard.
Quantity of the item that can be fulfilled by a shipment. Applies when delivery=shipment.
Quantity of the item that can be fulfilled by a subscription. Applies when delivery=subscription.
Total discount total for returned items.
Total price of returned items.
Total tax amount of returned items.
ID of location from /settings/shipping/locations. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used.
Indicates whether the item has stock tracking enabled.
Start date for subscription period.
Indicates the item has been fulfilled as a subscription and marked as paid by reference to this order.
Total tax amount divided by quantity.
Total tax applied to the item.
Total of all trial prices on the order.
Expandable link to the item variant, if applicable.
Quantity of items that can be canceled.
Amount of items credited.
Quantity of items eligible to be used with credit.
Quantity of items eligible to be invoiced.
Quantity of invoiced items.
Total quantity of items.
Quantity of subscriptions delivered.
Purchase option selected; standard for one-time purchases or subscription for a subscription plan.
Designates the type of purchase option: standard for one-time purchases, subscription for a subscription plan.
Possible enum values:
ID of the purchase option.
The name of the purchase option.
Price of the purchase option.
ID of the subscription plan, if applicable.
Name of the subscription plan, if applicable.
Billing schedule for the subscription plan, if applicable.
Billing interval for the subscription plan. Can be monthly, weekly, daily, or yearly.
Possible enum values:
Multiplier for the billing interval. For example, to make the subscription charge once every 2 weeks, set interval=weekly and interval_count=2.
Number of days the subscription trial period is for. An invoice will not be issued until trial has elapsed.
Specifies a limit to the number of billing cycles for the subscription plan. For example, "limit"=10 would stop billing the customer after the tenth billing cycle.
Frequency of order generation for the subscription plan. Can be monthly, daily, weekly, or yearly.
Possible enum values:
Multiplier when combined with order interval. For example, to generate an order every two weeks, set interval=weekly and interval_count=2.
Limit to number of orders generated for the purchase option.
The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.
ID of the customer's address on file.
Expandable link to the customer's address on file.
Shipping address line 1: street address/PO box/company name.
Shipping address line 2: apartment/suite/unit/building.
Shipping city/district/suburb/town/village.
Two-letter ISO country code.
Indicates shipping details represent the customer's default shipping address.
Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Shipping phone number.
Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.
ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.
Name of the shipping service. Defaults to shipment_rating.services.name chosen by setting service.
Shipping state/county/province/region.
Shipping zip/postal code.
Indicates whether shipping for local pick-up.
Amount of customer's account credit applied for initial payment, if applicable.
Indicates the customer chose to save shipping and billing information to their account when submitting the order.
Indicates the customer was logged into their account when placing the order.
A message describing the reason for cancelling the order, if applicable.
Indicates the order was completely canceled.
Customer notes provided when placing the order, if any.
ID of the coupon applied to the order.
Date the order was canceled, if applicable.
Indicates the order was marked as fulfilled, manually or automatically.
List of discounts applied to the order.
Unique identifier for the object.
Fixed discount amount.
Object describing the discount rule details. Custom discounts don't require this value.
Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.
Three-letter ISO currency code representing the user's preferred display currency, if applicable.
Locale code representing the user's preferred display locale, if applicable.
Optional message to include with the order when shipping to the recipient.
List of gift cards applied to the order.
Amount of the gift card balance to spend on this order. Defaults to giftcard.balance.
Specify a gift card code to apply to the order. If the code is not found or invalid, a validation error is returned. Case-insensitive.
Unique identifier for the object.
Fully formatted gift card code for display purposes.
Last four digits of the gift card code.
Expandable link to the gift card record.
Indicates the order is intended as a gift for the recipient.
Indicates the customer was not logged in when placing the order.
Indicates the order was placed on hold.
Indicates line item prices include taxes.
Arbitrary data, typically set in a checkout flow to store custom values. See Storefront API for details.
Internal admin notes, not visible to the customer.
Indicates the order was marked as paid, manually or automatically.
List of promotion IDs applied to the order.
Shipping discount applied by coupons, promotions, or custom logic.
Shipping tax amount, if applicable.
Indicates shipping total includes taxes, if applicable.
List of taxes applied to the order.
Unique identifier for the object.
Fixed tax amount.
Name of the tax rule. For example, "NY Sales Tax".
Priority indicates the order in which a tax rule was applied. Higher priority rules are added on top of other tax rules with a lower priority. Rules with the same priority are calculated excluding each other.
Tax percentage used in calculating the fixed amount.
Indicates the tax applies to shipping.
Expandable link to the customer's account.
The id of an authorized payment. When "Require payment authorization" is enabled in payment settings, the order will be rejected if initial payment fails.
Expandable link to an authorized payment.
ID of the cart that converted to this order, if applicable.
Expandable link to the cart.
Expandable link to the coupon applied to the order.
Expandable list of account credit transactions. Balance of these transactions is kept in balance.
Total amount of additional credit applied to the order.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Currency percentage used in calculating the fixed amount.
When automated payment has failed, this is the date when the system will automatically retry.
Period end date applicable when the order was created from a subscription.
Period start date applicable when the order was created from a subscription.
Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record.
Indicates the order was completely fulfilled. Always true when delivery_marked=true, otherwise depends on the sum of shipments, giftcards, and subscriptions.
Total discount amount.
Indicates the order has at least one line item with delivery=giftcard.
Total payment amount applied to the order from giftcards.
Grand total including items, shipping and taxes.
Expandable link to the invoice the payment was applied to, if applicable.
Total discount applied to line items.
Total quantity of all line items.
Total quantity of cancelable items on the order.
Total quantity of line items canceled.
Total quantity of line items that can be credited.
Total quantity of items credited on the order.
Total quantity of line items that can be fulfilled.
Total quantity of line items that have been fulfilled.
Total quantity of line items that can be fulfilled by gift card. Applies when item.delivery=giftcard.
Total quantity of items eligible for invoicing on the order.
Total quantity of items invoiced on the order.
Total quantity of line items that can still be returned.
Total quantity of line items that have been returned.
Total quantity of line items that can be fulfilled by shipment. Applies when item.delivery=shipment.
Total quantity of line items that can be fulfilled by subscription. Applies when item.delivery=subscription.
Total shipping weight of all line items.
Total taxes applied to line items.
Expandable list of notifications sent on behalf of the order.
Unique incremental order number, assigned automatically using a format configured in general settings.
Indicates the order was paid in full. Always true when payment_marked=true, otherwise depends on the sum of payments.
Expandable link to the parent order.
ID of the parent order.
Expandable list of payments applied to the order.
Balance of payments. A negative number indicates payment is owed, a positive balance indicates a refund is due, and a zero balance indicates fully paid.
A message describing the last payment error, if one occurred.
The number of times automatic payment has been attempted.
The method used to resolve automatic payment when all retry attempts are exhausted. Can be blank (do nothing), canceled, or unpaid.
Sum of payments applied to the order, not including refunds.
Expandable list of invoices that haven't been fully paid.
Expandable list of promotions applied to the order.
Indicates the order was marked as refunded, manually or automatically.
Sum of refunds on payments applied to the order.
Indicates the order was fully refunded. Always true when refund_marked=true, otherwise depends on the sum of refunds.
Expandable list of refunds applied to the order.
Total additional credit tax applied to the order from returns, if applicable
Total additional credit amount applied to the order from returns.
Total tax amount of items returned.
Total tax included amount of items returned, separate from line item values.
Total amount of items returned, minus discounts.
Grand total amount applied to the order from returns.
Indicates the order has at least one line item with delivery=shipment.
Total shipping price before discounts.
Object describing the shipping services and rates available for the order. Shipping country must be set before retrieving shipping rates.
List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here.
Unique code describing the error.
Message describing the error.
Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings.
List of shipping services and rates available.
Unique identifier for the object.
Name of a third-party carrier offering the service, if applicable.
Name of the shipping service.
Price of the shipping service.
Indicates whether shipping service is local pick-up.
Applicable tax code for shipment rating, if applicable.
Total shipping price including taxes and discount. Allows for an alternate display style as normally shipment_total and tax_total are shown separately.
Total shipping price after discounts.
Expandable list of shipments created from the order.
Current status of the order. Can be pending, draft, payment_pending, delivery_pending, hold, complete, or canceled.
Possible enum values:
Sum of all line items before discounts, taxes and shipping.
Indicates the order has at least one line item with delivery=subscription.
ID of the subscription that spawned the order, if applicable.
Expandable link to the subscription that spawned the order, if applicable.
Total of taxes applied separately from line items.
Total tax amount applied to the order including line items and shipping.
Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.
Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.
HTTP response status of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.
Indicates the order is tax-exempt. Taxes will not be calculated or applied when true.
Indicates that the order is a draft. Draft orders can also be designated as a cart with draft=true (as tracked within the Swell dashboard).
See the cart model for details.
Indicates the order was made in test mode.
Indicates the order is closed.
Total shipping price for items credited on the order.
This never gets set by Swell. A customer must explicitly set this field to a particular order ID.
If prev_id is set by the customer, prev will link to the order with the given prev_id.
This never gets set by Swell. A customer must explicitly set this field to a particular order ID.
If next_id is set by the customer, next will link to the order with the given next_id.
Indicates the customer’s account credit is applied when submitting the order.
Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record.
Scheduled date for the order.
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');
await swell.post('/orders', {
account_id: '5a9ea7ba3f95740a914267f1',
items: [
{
product_id: '5cad15bc9b14d1990724663a',
quantity: 2,
}
],
billing: {
...
},
shipping: {
...
},
coupon_code: 'FREESHIPPING',
});
Response
{
"id": "5cad15bc9b14d1990724663a",
"account_id": "5a9ea7ba3f95740a914267f1",
"billing": {...},
"shipping": {...},
"items": [
{
"id": "5a9ea7ba3f95740a914267f2",
"product_id": "5cad15bc9b14d1990724663b",
"quantity": 2,
"price": 9.99,
"price_total": 18.98,
"shipment_weight": 1.5,
...
}
],
"coupon_code": "FREESHIPPING",
"currency": "USD",
"date_created": "2019-04-01T00:00:00.000Z",
"delivered": false,
"discount_total": 0,
"grand_total": 18.98,
"item_quantity": 2,
"item_shipment_weight": 3.0,
"item_tax": 0,
"number": "100101",
"paid": false,
"payment_balance": -18.98,
"payment_total": 0,
"refund_total": 0,
"refunded": false,
"shipment_price": 0,
"shipment_total": 0,
"status": "payment_pending",
"sub_total": 0,
"tax_total": 0,
...
}