# Orders Source: https://developers.swell.is/backend-api/orders An order is a request to purchase products from a store. Orders contain all the information needed to fulfill a purchase. Usually, customers create a [cart](https://developers.swell.is/backend-api/carts/the-cart-model) to stage a purchase first and see it converted to an order when it's finalized. Besides being converted from a cart, it is possible to create an order directly. ## The order model ### Fields - `id` (objectId): Unique identifier for the order. - `account_id` (objectId, required): The `id` of the customer's account. During checkout, customer accounts without a password are designated as `guest=true`. - `account` (Account): Expandable link to the customer's account. - `account_credit_amount` (currency): Amount of customer's account credit applied for initial payment, if applicable. - `account_credit_applied` (boolean): Indicates the customer’s account credit is applied when submitting the order. - `account_info_saved` (boolean): Indicates the customer chose to save shipping and billing information to their account when submitting the order. - `account_logged_in` (boolean): Indicates the customer was logged into their account when placing the order. - `authorized_payment` (Payment): Expandable link to an authorized payment. - `authorized_payment_id` (string, auto): The id of an authorized payment. When "Require payment authorization" is enabled in payment settings, the order will be rejected if initial payment fails. - `billing` (object): The customer's billing details. Defaults to `account.billing`. Updating billing will also update the corresponding account billing object. - `name` (string): Billing full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `first_name` (string): Billing first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Billing last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `address1` (string): Billing address line 1: street address/PO box/company name. - `address2` (string): Billing address line 2: apartment/suite/unit/building. - `city` (string): Billing city/district/suburb/town/village. - `convesiopay` (object): ConvesioPay payment details. - `return_url` (string): URL the customer returns to after completing the ConvesioPay payment flow. - `state` (string): Billing state/county/province/region. - `vat_number` (string): VAT number associated with the billing address, if applicable. - `zip` (string): Billing zip/postal code. - `country` (string): Two-letter ISO country code. - `phone` (string): Billing phone number. - `method` (string): Method of payment. Can be `card`, `account`, `amazon`, `paypal`, or any one of the manual methods defined in payment settings. - `card` (object): Credit card billing details used when `billing.method=card`. - `token` (string, required): Token generated by Swell Checkout or [Stripe.js](https://stripe.com/docs/stripe-js/reference). - `exp_month` (int): Two-digit number representing the credit card expiration month. - `exp_year` (int): Four-digit number representing the credit card expiration year. - `brand` (string): Credit card brand. Can be `American Express`, `Diners Club`, `Discover`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`. - `display_brand` (string): Brand of the card displayed to the customer, if different from the underlying brand (for example, co-branded cards). - `last4` (string): Last four digits of the card number. - `gateway` (string): ID of the payment gateway that should be used to process payments. - `test` (boolean): Indicates this is a test card. - `address_check` (string): When used with a payment gateway that performs address checks and `address1` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `zip_check` (string): When used with a payment gateway that performs address checks and `zip` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `cvc_check` (string): When used with a payment gateway that performs CVC code checks and `cvc` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `default` (boolean): Indicates billing details represent the customer's default payment method. - `account_card_id` (objectId): ID of the customer's credit card on file, if applicable. - `account_card` (account_card): Expandable link to the customer's credit card on file, if applicable. - `amazon` (object): Amazon billing details used when `billing.method=amazon`. - `access_token` (string): Amazon access token provided when a customer authorizes payment in a storefront. - `order_reference_id` (string): Amazon order reference ID created when a customer initiates payment in a storefront. - `checkout_session_id` (string) - `paypal` (object): PayPal billing details used when `billing.method=paypal`. - `payer_id` (string): PayPal payer ID provided when a customer authorizes payment in a storefront. - `payment_id` (string): PayPal payment ID created when a customer initiates payment in a storefront. - `order_id` (string) - `intent` (object): Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized. - `affirm` (object): Affirm billing details used when `billing.method=affirm`. - `checkout_token` (string): Token used to communicate payment information to the gateway. - `resolve` (object): Resolve billing details used when `billing.method=resolve`. - `charge_id` (string): Charge ID returned by the payment gateway for the payment. - `sezzle` (object): Sezzle payment details. - `order_uuid` (string): Unique ID of the Sezzle order. - `klarna` (object): Klarna billing details used when `billing.method=klarna`. - `source` (string): Payment information returned by the gateway during payment initialization. - `ideal` (object): Ideal billing details used when `billing.method=ideal`. - `token` (string): Token used to communicate payment information to the gateway. - `bancontact` (object): Bancontact billing details used when `billing.method=bancontact`. - `source` (string): Payment information returned by the gateway during payment initialization. - `google` (object): Google Pay billing details used when `billing.method=google`. - `nonce` (string): One-time use reference element used to communicate payment information to a payment gateway. - `gateway` (string): Gateway used to facilitate the transaction. For example, `gateway=braintree`. - `apple` (object): Apple Pay billing details used when `billing.method=apple`. - `nonce` (string): One-time use reference element used to communicate payment information to a payment gateway. - `gateway` (string): Gateway used to facilitate the transaction. For example, `gateway=braintree`. - `instructions` (string) - `cancel_reason` (string): A message describing the reason for cancelling the order, if applicable. - `canceled` (boolean): Indicates the order was completely canceled. - `cart` (Cart): Expandable link to the cart. - `cart_id` (objectId, auto): ID of the cart that converted to this order, if applicable. - `closed` (boolean): Indicates the order is closed. Default: `false`. - `comments` (string): Customer notes provided when placing the order, if any. - `coupon` (Coupon): Expandable link to the coupon applied to the order. - `coupon_code` (string): [Coupon](https://developers.swell.is/backend-api/coupons) code applied to the order. - `coupon_id` (objectId): ID of the coupon applied to the order. - `credit_total` (currency): Total amount of additional credit applied to the order. - `credits` (Credit memo): Expandable list of account credit transactions. Balance of these transactions is kept in `balance`. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency. - `currency_rate` (float): Currency percentage used in calculating the fixed amount. - `location` (string): Location to purchase products from, when using multi-location inventory. - `date_canceled` (date): Date the order was canceled, if applicable. - `date_created` (date, auto): Date and time the order was created. - `date_payment_retry` (date): When automated payment has failed, this is the date when the system will automatically retry. - `date_period_end` (date, auto): Period end date applicable when the order was created from a `subscription`. - `date_period_start` (date, auto): Period start date applicable when the order was created from a `subscription`. - `date_scheduled` (date): Scheduled date for the order. - `date_updated` (date, auto): Date and time the order was last updated. - `date_webhook_first_failed` (date, auto): Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record. - `date_webhook_last_succeeded` (date): Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record. - `delivered` (boolean, auto): Indicates the order was completely fulfilled. Always `true` when `delivery_marked=true`, otherwise depends on the sum of `shipments`, `giftcards`, and `subscriptions`. Default: `false`. - `delivery_marked` (boolean): Indicates the order was marked as fulfilled, manually or automatically. - `discount_total` (currency, auto): Total discount amount. - `discounts` (array of object): List of discounts applied to the order. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed discount amount. - `type` (string): Type of discount. Can be `coupon` or `promo-` referring to the source of the discount. Custom discounts don't require this value. - `rule` (object): Object describing the discount rule details. Custom discounts don't require this value. - `source_id` (objectId): ID of the source object that generated the discount, such as a coupon or promotion. - `display_currency` (string): Three-letter ISO currency code representing the user's preferred display currency, if applicable. - `display_locale` (string): Locale code representing the user's preferred display locale, if applicable. - `gift` (boolean): Indicates the order is intended as a gift for the recipient. - `gift_message` (string): Optional message to include with the order when shipping to the recipient. - `giftcard_delivery` (boolean): Indicates the order has at least one line item with `delivery=giftcard`. - `giftcard_total` (currency): Total payment amount applied to the order from `giftcards`. - `giftcards` (array of object): List of gift cards applied to the order. - `id` (objectId): Unique identifier for the object. - `amount` (currency): Amount of the gift card balance to spend for initial payment. If not specified, each gift cards will be spent in order until payment is completed.` - `code` (string): Gift card code to apply. A validation error will be returned if the code is not valid. - `code_formatted` (string): Fully formatted gift card code for display purposes. - `last4` (string): Last four digits of the gift card code. - `giftcard` (giftcard): Expandable link to the gift card record. - `grand_total` (currency, auto): Grand total including items, shipping and taxes. - `trial_grand_total` (currency): Grand total of items with a trial period, charged when their trials end. - `guest` (boolean): Indicates the customer was not logged in when placing the order. Default: `{"$formula":"or(cart.guest, not(account_logged_in))"}`. - `hold` (boolean): Indicates the order was placed on hold. Default: `false`. - `invoices` (Invoice): Expandable link to the invoice the payment was applied to, if applicable. - `item_discount` (currency, auto): Total discount applied to line items. - `trial_item_discount` (currency): Total discount applied to items with a trial period. - `item_quantity` (int, auto): Total quantity of all line items. - `item_quantity_cancelable` (int): Total quantity of cancelable items on the order. - `item_quantity_canceled` (int, auto): Total quantity of line items canceled. - `item_quantity_creditable` (int): Total quantity of line items that can be credited. - `item_quantity_credited` (int): Total quantity of items credited on the order. - `item_quantity_deliverable` (int, auto): Total quantity of line items that can be fulfilled. - `item_quantity_delivered` (int, auto): Total quantity of line items that have been fulfilled. - `item_quantity_giftcard_deliverable` (int, auto): Total quantity of line items that can be fulfilled by gift card. Applies when `item.delivery=giftcard`. - `item_quantity_invoiceable` (int): Total quantity of items eligible for invoicing on the order. - `item_quantity_invoiced` (int): Total quantity of items invoiced on the order. - `item_quantity_returnable` (int, auto): Total quantity of line items that can still be returned. - `item_quantity_returned` (int, auto): Total quantity of line items that have been returned. - `item_quantity_shipment_deliverable` (int, auto): Total quantity of line items that can be fulfilled by shipment. Applies when `item.delivery=shipment`. - `item_quantity_subscription_deliverable` (int, auto): Total quantity of line items that can be fulfilled by subscription. Applies when `item.delivery=subscription`. - `item_shipment_weight` (float): Total shipping weight of all line items. - `item_tax` (currency, auto): Total taxes applied to line items. - `trial_item_tax` (currency): Total tax applied to items with a trial period. - `item_tax_included` (boolean): Indicates line item prices include taxes. - `items` (array of object): List of line items describing the products ordered. - `id` (objectId, auto): Unique identifier for the item. - `location` (string): Location the item is fulfilled from, when using multi-location inventory. - `location_selected` (string): Location explicitly selected for the item, when using multi-location inventory. - `bundle_items` (array of object): List of items offered as a bundle. Defaults to `product.bundle_items`. - `id` (objectId, auto): Unique identifier for the object. - `product_id` (objectId, required): ID of the bundle item product. - `delivery` (enum): Method of delivery taken automatically from `product.delivery`. Possible values: `shipment`, `giftcard`, `subscription`. - `options` (array of object): 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. Subscription products have three special options that are used when fulfilling subscriptions. Use the option ID `subscription_interval` with a value of `daily`, `weekly`, `monthly`, `yearly`, and `subscription_interval_count` with an integer value used as a multiplier of the interval (defaults to 1), and `subscription_trial_days` to indicate the number of days the subscription should be in trial status after being created. 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. - `id` (string): Unique identifier for the object. - `name` (string): Name of the product option. Populated automatically when adding an option by ID. - `price` (currency): Additional price added onto the base price of the product. - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product. - `value` (string): 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. - `variant` (boolean): Indicates the option refers to a variant aspect. - `value_id` (objectId): ID of the associated value. - `location` (string): Location associated with the option value, when using multi-location inventory. - `product` (product): Expandable link to the bundle item product. - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`. - `quantity_canceled` (int): Quantity of the bundle item canceled before fulfillment, if applicable. Default: `0`. - `quantity_consumed` (int): Quantity of stock consumed by the bundle item, if applicable. - `quantity_deliverable` (int): Quantity of the bundle item that can be fulfilled, if applicable. - `quantity_delivered` (int): Quantity of the bundle item that has been fulfilled, if applicable. Default: `0`. - `quantity_giftcard_deliverable` (int): Quantity of the bundle item that can be fulfilled by a gift card. Applies when `delivery=giftcard`. - `quantity_restocked` (int): Quantity of the bundle item that has been restocked after a return, if applicable. - `quantity_returnable` (int): Quantity of the bundle item that can still be returned after fulfillment, if applicable. - `quantity_returned` (int): Total quantity of bundle items that have been returned. - `quantity_shipment_deliverable` (int): Quantity of the bundle item that can be fulfilled by a shipment. Applies when `delivery=shipment`. - `quantity_total` (int): Total quantity of the bundle item to be fulfilled, calculated as `item.quantity * bundle_item.quantity`. - `shipment_weight` (float): Shipping weight taken automatically from `product.shipment_weight`, if applicable. - `return_price_total` (currency): Total price of returned units of the bundle item. - `return_discount_total` (currency): Total discount of returned units of the bundle item. - `return_tax_total` (currency): Total tax of returned units of the bundle item. - `stock_tracking` (boolean): Indicates whether the bundle item has stock tracking enabled. - `variant_id` (objectId): ID of the bundle item variant. - `variant_name` (string): Name of the variant. - `variant` (variant): Expandable link to the bundle item variant. - `quantity_shipment_delivered` (int): Quantity of shipments that have been delivered. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula":"if(product_id, product.name, null)"}`. - `price` (currency): Price of the bundle item. - `discount_each` (currency): Discount amount applied to each unit of the bundle item. - `tax_each` (currency): Tax amount applied to each unit of the bundle item. - `amount_ratio` (float): Ratio of the bundle price allocated to this item. - `delivery` (enum): Method of delivery taken automatically from `product.delivery`. Possible values: `shipment`, `giftcard`, `subscription`. - `description` (string): Description used for custom line items, when product is not defined. - `discount_each` (currency): Total discount amount divided by quantity. - `discount_total` (currency): Total discount applied to the item. - `discounts` (array of object): List of discounts applied to the item by [coupons](https://developers.swell.is/backend-api/coupons/the-coupon-model), [promotions](https://developers.swell.is/backend-api/promotions/the-promotion-model), or custom logic. - `id` (string): Unique identifier for the object. Refers to one of the IDs in the order `discounts` object. - `amount` (currency): Fixed discount amount. - `metadata` (object): Arbitrary item data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for details. - `options` (array of object): 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. Subscription products have three special options that are used when fulfilling subscriptions. Use the option ID `subscription_interval` with a value of `daily`, `weekly`, `monthly`, `yearly`, and `subscription_interval_count` with an integer value used as a multiplier of the interval (defaults to 1), and `subscription_trial_days` to indicate the number of days the subscription should be in trial status after being created. 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. - `id` (string): Unique identifier for the object. - `name` (string): Name of the product option. Populated automatically when adding an option by ID. - `price` (currency): Additional price added onto the base price of the product. - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product. - `value` (string): 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. - `variant` (boolean): Indicates the option refers to a variant aspect. - `value_id` (objectId): ID of the associated value. - `orig_price` (currency): Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed. - `price` (currency): Price of the item. If a product price is reduced by a sale or price rule, this would be set to the reduced price automatically. Also, item price can be overridden when adding to an order. Line item prices don't change unless explicitly edited by a store admin. Default: `{"$formula":"if(product_id, product.price)"}`. - `price_total` (currency): Total price added to sub total by multiplying `quantity` and `price`. - `product_id` (objectId): ID of the item product. - `product` (product): Expandable link to the item product. - `product_name` (string): Name of the product. Default: `{"$formula":"if(product_id, product.name, null)"}`. - `quantity` (int): Quantity of the item being ordered. Defaults to 1. Default: `1`. - `quantity_canceled` (int): Quantity of the item canceled before fulfillment, if applicable. Default: `0`. - `quantity_consumed` (int): Quantity of stock consumed by the item, if applicable. - `quantity_deliverable` (int): Quantity of the item that can be fulfilled, if applicable. - `quantity_delivered` (int): Quantity of the item that has been fulfilled, if applicable. Default: `0`. - `quantity_giftcard_deliverable` (int): Quantity of the item that can be fulfilled by a gift card. Applies when `delivery=giftcard`. - `quantity_restocked` (int): Quantity of the item that has been restocked after a return, if applicable. - `quantity_returnable` (int): Quantity of the item that can still be returned after fulfillment, if applicable. - `quantity_returned` (int): Quantity of the item that has been returned after fulfillment, if applicable. - `quantity_shipment_deliverable` (int): Quantity of the item that can be fulfilled by a shipment. Applies when `delivery=shipment`. - `quantity_subscription_deliverable` (int): Quantity of the item that can be fulfilled by a subscription. Applies when `delivery=subscription`. - `shipment_location` (string): ID of location from `/settings/shipping/locations`. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used. - `shipment_weight` (float): Shipping weight taken automatically from `product.shipment_weight`, if applicable. - `stock_tracking` (boolean): Indicates whether the item has stock tracking enabled. - `subscription_paid` (boolean): Indicates the item has been fulfilled as a [subscription](https://developers.swell.is/backend-api/subscriptions/the-subscription-model) and marked as `paid by reference to this order.` - `tax_each` (currency): Total tax amount divided by quantity. - `tax_total` (currency): Total tax applied to the item. - `trial` (boolean): Indicates the item has a trial period. - `trial_price_total` (currency): Total price of the item during its trial period, charged when the trial ends. - `trial_discount_total` (currency): Total discount applied to the item's trial price. - `trial_tax_total` (currency): Total tax applied to the item's trial price. - `taxes` (array of object): List of tax rules applied to the item based on tax settings or custom logic. - `id` (string): Unique identifier for the object. Refers to one of the IDs in the order `taxes` object. - `amount` (currency): Fixed tax amount. - `variant_id` (objectId): ID of the item variant, if applicable. - `variant_name` (string): Name of the variant. - `variant` (variant): Expandable link to the item variant, if applicable. - `metadata` (object): Arbitrary data, typically set in a checkout flow to store custom values. See [Frontend API](https://developers.swell.is/frontend-api/introduction) for details. - `next` (Order): If `next_id` is set by the customer, `next` will link to the order with the given `next_id`. - `next_id` (objectId): This never gets set by Swell. A customer must explicitly set this field to a particular order ID. - `notes` (string): Internal admin notes, not visible to the customer. This field holds a single block of text. To record a series of notes against the order, each attributed to a user, see [Notes](https://developers.swell.is/backend-api/notes). - `notifications` (Notification): Expandable list of notifications sent on behalf of the order. - `number` (string, auto): Unique incremental order number, assigned automatically using a format configured in general settings. - `paid` (boolean, auto): Indicates the order was paid in full. Always `true` when `payment_marked=true`, otherwise depends on the sum of `payments`. Default: `false`. - `parent` (Order): Expandable link to the parent order. - `parent_id` (objectId): ID of the parent order. - `payment_balance` (currency, auto): 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. - `payment_error` (string): A message describing the last payment error, if one occurred. - `payment_marked` (boolean): Indicates the order was marked as paid, manually or automatically. - `payment_retry_count` (int): The number of times automatic payment has been attempted. - `payment_retry_resolve` (string): The method used to resolve automatic payment when all retry attempts are exhausted. Can be blank (do nothing), `canceled`, or `unpaid`. - `payment_total` (currency): Sum of payments applied to the order, not including refunds. Default: `0`. - `payments` (Payment): Expandable list of payments applied to the order. - `pending_invoices` (Invoice): Expandable list of invoices that haven't been fully paid. - `prev` (Order): If `prev_id` is set by the customer, `prev` will link to the order with the given `prev_id`. - `prev_id` (objectId): This never gets set by Swell. A customer must explicitly set this field to a particular order ID. - `promotion_ids` (array of child_scalar): List of promotion IDs applied to the order. - `promotions` (Promotion): Expandable list of promotions applied to the order. - `refund_marked` (boolean): Indicates the order was marked as refunded, manually or automatically. - `refund_total` (currency): Sum of refunds on payments applied to the order. Default: `0`. - `refunded` (boolean, auto): Indicates the order was fully refunded. Always `true` when `refund_marked=true`, otherwise depends on the sum of `refunds`. Default: `false`. - `refunds` (Refund): Expandable list of refunds applied to the order. - `return_credit_tax` (currency): Total additional credit tax applied to the order from returns, if applicable - `return_credit_total` (currency): Total additional credit amount applied to the order from returns. - `return_item_tax` (currency, auto): Total tax amount of items returned. - `return_item_tax_included` (currency, auto): Total tax included amount of items returned, separate from line item values. - `return_item_total` (currency, auto): Total amount of items returned, minus discounts. - `return_total` (currency): Grand total amount applied to the order from returns. - `schedule` (object): Scheduling for recurring orders. - `interval` (enum): Recurring order interval, if applicable. Can be `monthly`, `daily`, `weekly`, or `yearly`. Possible values: `monthly`, `daily`, `weekly`, `yearly`. - `interval_count` (int): Multiplier for billing interval. For example, to make the subscription charge once every two weeks, set `interval=weekly` and `interval_count=2.` - `shipment_delivery` (boolean): Indicates the order has at least one line item with `delivery=shipment`. - `shipment_discount` (currency): Shipping discount applied by [coupons](https://developers.swell.is/backend-api/coupons), [promotions](https://developers.swell.is/backend-api/promotions), or custom logic. - `shipment_price` (currency, auto): Total shipping price before discounts. - `shipment_rating` (object, auto): Object describing the shipping services and rates available for the order. Shipping `country` must be set before retrieving shipping rates. - `date_created` (date, auto): Date and time the object was created. - `errors` (array of object): List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here. - `code` (string): Unique code describing the error. - `message` (string): Message describing the error. - `fingerprint` (string): Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings. - `services` (array of object): List of shipping services and rates available. - `id` (string): Unique identifier for the object. - `carrier` (string): Name of a third-party carrier offering the service, if applicable. - `name` (string): Name of the shipping service. - `price` (currency): Price of the shipping service. - `pickup` (boolean): Indicates whether shipping service is local pick-up. - `extension_app_id` (objectId): ID of the app that provided the shipping rate through a shipping extension, if applicable. - `extension_config_id` (string): ID of the extension configuration that provided the shipping rate, if applicable. - `shipment_tax` (currency): Shipping tax amount, if applicable. - `shipment_tax_included` (boolean): Indicates shipping total includes taxes, if applicable. - `shipment_tax_included_total` (currency, auto): Total shipping price including taxes and discount. Allows for an alternate display style as normally `shipment_total` and `tax_total` are shown separately. - `shipment_total` (currency, auto): Total shipping price after discounts. - `shipment_total_credited` (currency): Total shipping price for items credited on the order. - `shipments` (Shipment): Expandable list of shipments created from the order. - `shipping` (object): The customer's shipping details. Defaults to `account.shipping`. Updating shipping will also update the corresponding account shipping object. - `name` (string): Shipping full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `first_name` (string): Shipping first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Shipping last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `address1` (string): Shipping address line 1: street address/PO box/company name. - `address2` (string): Shipping address line 2: apartment/suite/unit/building. - `city` (string): Shipping city/district/suburb/town/village. - `state` (string): Shipping state/county/province/region. - `tax_id` (string): Tax identification number of the recipient, where required for customs or delivery. - `zip` (string): Shipping zip/postal code. - `country` (string): Two-letter ISO country code. - `phone` (string): Shipping phone number. - `service` (string): ID of a shipping service as configured in shipment settings. Normally, this would be applied after [retrieving shipping rates](https://developers.swell.is/backend-api/shipments/retrieve-a-shipment) by using one of the `shipment_rating.services.id` values. - `service_name` (string): Name of the shipping service. Defaults to `shipment_rating.services.name` chosen by setting `service`. - `price` (currency): Price of the shipping service. Defaults to `shipment_rating.services.price` chosen by setting `service`. - `default` (boolean): Indicates shipping details represent the customer's default shipping address. - `account_address_id` (objectId): ID of the customer's address on file. - `account_address` (account_address): Expandable link to the customer's address on file. - `pickup` (boolean): Indicates whether shipping for local pick-up. - `status` (enum, auto): Current status of the order. Can be `pending`, `draft`, `payment_pending`, `delivery_pending`, `hold`, `complete`, or `canceled`. Possible values: `pending`, `draft`, `payment_pending`, `delivery_pending`, `hold`, `complete`, `canceled`. Default: `"pending"`. - `sub_total` (currency, auto): Sum of all line items before discounts, taxes and shipping. - `trial_sub_total` (currency): Subtotal of items with a trial period, charged when their trials end. - `subscription` (Subscription): Expandable link to the subscription that spawned the order, if applicable. - `subscription_delivery` (boolean): Indicates the order has at least one line item with `delivery=subscription`. - `subscription_id` (objectId, auto): ID of the subscription that spawned the order, if applicable. - `tax_included_total` (currency, auto): Total of taxes applied separately from line items. - `trial_tax_included_total` (currency): Total of items with a trial period including taxes, if applicable. - `tax_total` (currency, auto): Total tax amount applied to the order including line items and shipping. - `taxes` (array of object): List of taxes applied to the order. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed tax amount. - `name` (string): Name of the tax rule. For example "NY Sales Tax". - `priority` (int): 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. - `extension_app_id` (objectId): ID of the app that provided the tax calculation through a tax extension, if applicable. - `extension_config_id` (string): ID of the extension configuration that provided the tax calculation, if applicable. - `rate` (float): Tax percentage used in calculating the fixed amount. - `shipping` (boolean): Indicates the tax applies to shipping. - `taxes_fixed` (boolean): Indicates the order is tax-exempt. Taxes will not be calculated or applied when true. - `test` (boolean): Indicates the order was made in test mode. - `trial` (boolean): Indicates the order contains at least one item with a trial period. - `webhook_attempts_failed` (int, auto): Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_response` (string, auto): Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_status` (int, auto): 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. ### Example response ```json { "cart_id": "62bc6389912a9800199ea43a", "draft": false, "test": true, "items": [ { "product_id": "628ba3c7499bba0019b1a961", "quantity": 1, "price": 25, "purchase_option": { "type": "standard", "price": 25 }, "id": "62bc63892fafef0019eb2312", "orig_price": 25, "delivery": "shipment", "shipment_weight": 0, "price_total": 25, "discount_total": 3.75, "discount_each": 3.75, "tax_total": 0, "tax_each": 0, "discounts": [ { "id": "promo-62bc63e193cb7c0019423b6e-0", "amount": 3.75 } ], "product_name": "Mannimarco, King of Worms", "quantity_total": 1, "quantity_invoiceable": 1, "quantity_creditable": 1, "quantity_cancelable": 0, "quantity_deliverable": 0, "quantity_shipment_deliverable": 0, "quantity_canceled": 0, "quantity_delivered": 1, "quantity_returnable": 1 }, { "product_id": "628ba442499bba0019b1a96d", "quantity": 1, "price": 25, "purchase_option": { "type": "standard", "price": 25 }, "id": "62bc639293cb7c0019423b5f", "orig_price": 25, "delivery": "shipment", "shipment_weight": 0, "price_total": 25, "discount_total": 3.75, "discount_each": 3.75, "tax_total": 0, "tax_each": 0, "discounts": [ { "id": "promo-62bc63e193cb7c0019423b6e-0", "amount": 3.75 } ], "product_name": "Calcinator Treatise", "quantity_total": 1, "quantity_invoiceable": 1, "quantity_creditable": 1, "quantity_cancelable": 0, "quantity_deliverable": 0, "quantity_shipment_deliverable": 0, "quantity_canceled": 0, "quantity_delivered": 1, "quantity_returnable": 1 }, { "product_id": "628ba6011869c10019b41f70", "quantity": 1, "price": 60, "purchase_option": { "type": "standard", "price": 60 }, "id": "62bc639e629aa900197ff786", "orig_price": 60, "delivery": "shipment", "shipment_weight": 0, "price_total": 60, "discount_total": 9, "discount_each": 9, "tax_total": 0, "tax_each": 0, "discounts": [ { "id": "promo-62bc63e193cb7c0019423b6e-0", "amount": 9 } ], "product_name": "Mythic Dawn Commentaries I", "quantity_total": 1, "quantity_invoiceable": 1, "quantity_creditable": 1, "quantity_cancelable": 0, "quantity_deliverable": 0, "quantity_shipment_deliverable": 0, "quantity_canceled": 0, "quantity_delivered": 1, "quantity_returnable": 1 }, { "product_id": "628ba67a1869c10019b41f76", "quantity": 1, "price": 60, "purchase_option": { "type": "standard", "price": 60 }, "id": "62bc63a293cb7c0019423b63", "orig_price": 60, "delivery": "shipment", "shipment_weight": 0, "price_total": 60, "discount_total": 9, "discount_each": 9, "tax_total": 0, "tax_each": 0, "discounts": [ { "id": "promo-62bc63e193cb7c0019423b6e-0", "amount": 9 } ], "product_name": "Mythic Dawn Commentaries II", "quantity_total": 1, "quantity_invoiceable": 1, "quantity_creditable": 1, "quantity_cancelable": 0, "quantity_deliverable": 0, "quantity_shipment_deliverable": 0, "quantity_canceled": 0, "quantity_delivered": 1, "quantity_returnable": 1 }, { "product_id": "628ba6b7499bba0019b1a9b2", "quantity": 1, "price": 60, "purchase_option": { "type": "standard", "price": 60 }, "id": "62bc63a793cb7c0019423b66", "orig_price": 60, "delivery": "shipment", "shipment_weight": 0, "price_total": 60, "discount_total": 9, "discount_each": 9, "tax_total": 0, "tax_each": 0, "discounts": [ { "id": "promo-62bc63e193cb7c0019423b6e-0", "amount": 9 } ], "product_name": "Mythic Dawn Commentaries III", "quantity_total": 1, "quantity_invoiceable": 1, "quantity_creditable": 1, "quantity_cancelable": 0, "quantity_deliverable": 0, "quantity_shipment_deliverable": 0, "quantity_canceled": 0, "quantity_delivered": 1, "quantity_returnable": 1 }, { "product_id": "628ba701499bba0019b1a9bb", "quantity": 1, "price": 60, "purchase_option": { "type": "standard", "price": 60 }, "id": "62bc63aa93cb7c0019423b69", "orig_price": 60, "delivery": "shipment", "shipment_weight": 0, "price_total": 60, "discount_total": 9, "discount_each": 9, "tax_total": 0, "tax_each": 0, "discounts": [ { "id": "promo-62bc63e193cb7c0019423b6e-0", "amount": 9 } ], "product_name": "Myuthic Dawn Commentaries IV", "quantity_total": 1, "quantity_invoiceable": 1, "quantity_creditable": 1, "quantity_cancelable": 0, "quantity_deliverable": 0, "quantity_shipment_deliverable": 0, "quantity_canceled": 0, "quantity_delivered": 1, "quantity_returnable": 1 } ], "billing": { "card": { "brand": "Visa", "last4": "4242", "exp_month": 3, "exp_year": 2024, "token": "card_XW3WxpzAmGBPGLFmxsLT1oZY", "address_check": "unchecked", "zip_check": "unchecked", "cvc_check": "unchecked", "fingerprint": "883f20e8bc00d0f9e1c42967b39a4f22", "date_created": "2022-06-24T16:45:03.577Z" }, "first_name": "Sheogorath", "last_name": null, "address1": "New Sheoth Palace", "address2": null, "city": "Shivering Isles", "state": "TX", "zip": "78757", "country": "US", "phone": null, "company": null, "account_card_id": null, "method": "card", "use_account": false, "default": false, "name": "Sheogorath" }, "shipping": { "service": "international", "price": null, "service_name": "International", "first_name": "Sheogorath", "last_name": null, "company": "", "address1": "New Sheoth Palace", "address2": null, "city": "Shivering Isles", "zip": "78757", "country": "US", "state": "TX", "phone": null, "default": false, "name": "Sheogorath" }, "shipment_rating": { "date_created": "2022-06-29T14:42:04.067Z", "fingerprint": "bc218e4a538adbdffe60fbb91dd6063e", "services": [ { "id": "standard", "name": "Standard Shipping", "price": 5, "description": "Standard shipping service" }, { "id": "express", "name": "Express Shipping", "price": 15, "description": "Express shipping service" } ] }, "shipment_discount": 0, "schedule": null, "coupon_code": null, "coupon_id": null, "discounts": [ { "type": "promo-62bc63e193cb7c0019423b6e", "rule": { "value_type": "percent", "value_percent": 15, "total_min": 100, "type": "total" }, "amount": 43.5, "id": "promo-62bc63e193cb7c0019423b6e-0" } ], "taxes": null, "item_tax_included": null, "shipment_tax": null, "shipment_tax_included": null, "promotion_ids": [ "62bc63e193cb7c0019423b6e" ], "account_id": "62991607782f3b0013cf17af", "account_logged_in": null, "account_info_saved": false, "account_credit_applied": null, "account_credit_amount": null, "giftcards": null, "currency": "USD", "display_currency": null, "display_locale": null, "notes": "Do we deliver to the Shivering Isles?", "comments": null, "gift": null, "gift_message": null, "metadata": null, "shipment_delivery": true, "date_trial_end": null, "sub_total": 290, "shipment_price": 0, "shipment_total": 0, "item_tax": 0, "tax_included_total": 0, "item_discount": 43.5, "discount_total": 43.5, "grand_total": 246.5, "item_quantity_returned": 0, "return_item_total": 0, "return_item_tax": 0, "return_item_tax_included": 0, "return_total": 0, "payment_balance": 0, "paid": true, "refunded": false, "item_quantity_delivered": 6, "item_quantity_deliverable": 0, "delivered": true, "item_quantity": 6, "item_quantity_canceled": 0, "item_quantity_cancelable": 0, "item_quantity_shipment_deliverable": 0, "item_quantity_returnable": 6, "item_quantity_invoiced": 0, "item_quantity_invoiceable": 6, "item_quantity_credited": 0, "item_quantity_creditable": 6, "item_shipment_weight": 0, "shipment_tax_included_total": 0, "tax_total": 0, "giftcard_total": 0, "guest": true, "authorized_payment_id": "62bc642d912a9800199ea467", "date_created": "2022-06-29T14:39:42.350Z", "hold": false, "closed": false, "status": "complete", "payment_total": 246.5, "refund_total": 0, "number": "100019", "date_updated": "2022-06-29T14:42:04.247Z", "payment_marked": true, "auto_update_account_address": false, "id": "62bc642d912a9800199ea465" } ``` ## Create an order Create a new order. ### Arguments - `account_id` (objectId, required): ID of the customer's account. - `billing` (object): The customer's billing details. Defaults to `account.billing`. Updating billing will also update the corresponding account billing object. - `account_card_id` (objectId): ID of the customer's credit card on file, if applicable. - `account_card` (account_card): Expandable link to the customer's credit card on file, if applicable. - `address1` (string): Billing address line 1: street address/PO box/company name. - `address2` (string): Billing address line 2: apartment/suite/unit/building. - `amazon` (object): Amazon billing details used when `billing.method=amazon`. - `access_token` (string): Amazon access token provided when a customer authorizes payment in a storefront. - `order_reference_id` (string): Amazon order reference ID created when a customer initiates payment in a storefront. - `checkout_session_id` (string) - `card` (object): Credit card billing details used when `billing.method=card`. - `token` (string): Token generated by Swell Checkout or [Stripe.js](https://stripe.com/docs/stripe-js/reference). - `exp_month` (int): Two-digit number representing the credit card expiration month. - `exp_year` (int): Four-digit number representing the credit card expiration year. - `brand` (string): Credit card brand. Can be `American Express`, `Diners Club`, `Discover`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`. - `last4` (string): Last four digits of the card number. - `gateway` (string): ID of the payment gateway that should be used to process payments. - `test` (boolean): Indicates this is a test card. - `address_check` (string): When used with a payment gateway that performs address checks and `address1` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `zip_check` (string): When used with a payment gateway that performs address checks and `zip` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `cvc_check` (string): When used with a payment gateway that performs CVC code checks and `cvc` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `city` (string): Billing city/district/suburb/town/village. - `country` (string): Two-letter ISO code country code. - `first_name` (string): Billing first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Billing last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `method` (string): Method of payment. Can be `card`, `account`, `amazon`, `paypal`, or any one of the manual methods defined in payment settings. - `name` (string): Billing full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `paypal` (object): PayPal billing details used when `billing.method=paypal`. - `payer_id` (string): PayPal payer ID provided when a customer authorizes payment in a storefront. - `payment_id` (string): PayPal payment ID created when a customer initiates payment in a storefront. - `order_id` (string) - `phone` (string): Billing phone number. - `state` (string): Billing state/county/province/region. - `zip` (string): Billing zip/postal code. - `default` (boolean): Indicates billing details represent the customer's default payment method. - `instructions` (string) - `coupon_code` (string): Coupon code applied to the order. See [coupons](https://developers.swell.is/backend-api/coupons/the-coupon-model) for details. - `items` (array of object): List of line items describing the products ordered. - `bundle_items` (array of object): List of items offered as a bundle. Defaults to `product.bundle_items`. - `product_id` (objectId, required): ID of the bundle item product. - `product` (product): Expandable link to the bundle item product. - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`. - `shipment_weight` (float): Weight to be used in shipping calculation, if applicable. - `quantity_restocked` (int): Quantity of the bundle item that has been restocked after a return, if applicable. - `quantity_returnable` (int): Quantity of the bundle item that can still be returned after fulfillment, if applicable. - `variant_id` (objectId): ID of the bundle item variant. - `variant` (variant): Expandable link to the bundle item product variant. - `id` (objectId, auto): Unique identifier for the object. - `delivery` (enum): Method of delivery taken automatically from `product.delivery`. Possible values: `shipment`, `giftcard`, `subscription`. - `options` (array of object): 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. - `id` (string): Unique identifier for the object. - `name` (string): Name of the product option. Populated automatically when adding an option by ID. - `price` (currency): Additional price added onto the base price of the product. - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product. - `value` (string): 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. - `value_id` (objectId): ID of the associated value. - `variant` (boolean): Indicates the option refers to a variant aspect. - `quantity_canceled` (int): Quantity of the bundle item canceled before fulfillment, if applicable. Default: `0`. - `quantity_consumed` (int): Quantity of stock consumed by the bundle item, if applicable. - `quantity_deliverable` (int): Quantity of the bundle item that can be fulfilled, if applicable. - `quantity_delivered` (int): Quantity of the bundle item that has been fulfilled, if applicable. Default: `0`. - `quantity_giftcard_deliverable` (int): Quantity of the bundle item that can be fulfilled by a gift card. Applies when `delivery=giftcard`. - `quantity_returned` (int): Total quantity of bundle items that have been returned. - `quantity_shipment_deliverable` (int): Quantity of the bundle item that can be fulfilled by a shipment. Applies when `delivery=shipment`. - `quantity_total` (int): Total quantity of the bundle item to be fulfilled, calculated as `item.quantity * bundle_item.quantity`. - `stock_tracking` (boolean): Indicates whether the bundle item has stock tracking enabled. - `quantity_shipment_delivered` (int): Quantity of shipments that have been delivered. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula":"if(product_id, product.name, null)"}`. - `description` (string): Description used for custom line items, when product is not defined. - `discounts` (array of object): List of discounts to apply to the item. Normally populated by applying a [coupon](https://developers.swell.is/backend-api/coupons/the-coupon-model) or [promotions.](https://developers.swell.is/backend-api/promotions/the-promotion-model) - `id` (string, required): Unique identifier for the object. Should refer to one of the IDs in the order `discounts` object. - `amount` (currency, required): Fixed discount amount. - `metadata` (object): Arbitrary item data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for details. - `options` (array of object): 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. - `id` (string): Unique identifier for the object. - `name` (string): Name of the product option. Populated automatically when adding an option by ID. - `price` (currency): Additional price added onto the base price of the product. - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product. - `value` (string): 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. - `value_id` (objectId): ID of the associated value. - `variant` (boolean): Indicates the option refers to a variant aspect. - `price` (currency): Price of the item. Override this value to set a custom price. Defaults to product price or sale price. Default: `{"$formula":"if(product_id, product.price)"}`. - `product_id` (objectId): ID of the item product. - `quantity` (int): Quantity of the item being ordered. Defaults to 1. Default: `1`. - `quantity_restocked` (int): Quantity of the item that has been restocked after a return, if applicable. - `quantity_returnable` (int): Quantity of the item that can still be returned after fulfillment, if applicable. - `quantity_returned` (int): Quantity of the item that has been returned after fulfillment, if applicable. - `shipment_weight` (float): Weight to be used in shipping calculation, if applicable. - `taxes` (array of object): List of tax rules to apply to the item. Normally populated by tax settings. - `id` (string, required): Unique identifier for the object. Should refer to one of the IDs in the order `taxes` object. - `amount` (currency, required): Fixed tax amount. - `variant_id` (objectId): ID of the item variant, if applicable. - `id` (objectId, auto): Unique identifier for the item. - `delivery` (enum): Method of delivery taken automatically from `product.delivery`. Possible values: `shipment`, `giftcard`, `subscription`. - `discount_each` (currency): Total discount amount divided by quantity. - `discount_total` (currency): Total discount applied to the item. - `orig_price` (currency): Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed. - `price_total` (currency): Total price added to sub total by multiplying `quantity` and `price`. - `product` (product): Expandable link to the item product. - `product_name` (string): Name of the product. Default: `{"$formula":"if(product_id, product.name, null)"}`. - `quantity_canceled` (int): Quantity of the item canceled before fulfillment, if applicable. Default: `0`. - `quantity_consumed` (int): Quantity of stock consumed by the item, if applicable. - `quantity_deliverable` (int): Quantity of the item that can be fulfilled, if applicable. - `quantity_delivered` (int): Quantity of the item that has been fulfilled, if applicable. Default: `0`. - `quantity_giftcard_deliverable` (int): Quantity of the item that can be fulfilled by a gift card. Applies when `delivery=giftcard`. - `quantity_shipment_deliverable` (int): Quantity of the item that can be fulfilled by a shipment. Applies when `delivery=shipment`. - `quantity_subscription_deliverable` (int): Quantity of the item that can be fulfilled by a subscription. Applies when `delivery=subscription`. - `shipment_location` (string): ID of location from `/settings/shipping/locations`. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used. - `stock_tracking` (boolean): Indicates whether the item has stock tracking enabled. - `subscription_paid` (boolean): Indicates the item has been fulfilled as a [subscription](https://developers.swell.is/backend-api/subscriptions/the-subscription-model) and marked as `paid by reference to this order.` - `tax_each` (currency): Total tax amount divided by quantity. - `tax_total` (currency): Total tax applied to the item. - `trial_price_total` (currency): Total of all trial prices on the order. - `variant` (variant): Expandable link to the item variant, if applicable. - `shipping` (object): The customer's shipping details. Defaults to `account.shipping`. Updating shipping will also update the corresponding account shipping object. - `account_address_id` (objectId): ID of the customer's address on file. - `account_address` (account_address): Expandable link to the customer's address on file. - `address1` (string): Shipping address line 1: street address/PO box/company name. - `address2` (string): Shipping address line 2: apartment/suite/unit/building. - `city` (string): Shipping city/district/suburb/town/village. - `country` (string): Two-letter ISO country code. - `default` (boolean): Indicates shipping details represent the customer's default shipping address. - `first_name` (string): Shipping first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Shipping last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `name` (string): Shipping full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `phone` (string): Shipping phone number. - `price` (currency): Price of the shipping service. Defaults to `shipment_rating.services.price` chosen by setting `service`. - `service` (string): ID of a shipping service as configured in shipment settings. Normally, this would be applied after [retrieving shipping rates](https://developers.swell.is/backend-api/shipments/retrieve-a-shipment) by using one of the `shipment_rating.services.id` values. - `service_name` (string): Name of the shipping service. Defaults to `shipment_rating.services.name` chosen by setting `service`. - `state` (string): Shipping state/county/province/region. - `zip` (string): Shipping zip/postal code. - `pickup` (boolean): Indicates whether shipping for local pick-up. - `account_credit_amount` (currency): Amount of customer's account credit applied for initial payment, if applicable. - `account_info_saved` (boolean): Indicates the customer chose to save shipping and billing information to their account when submitting the order. - `account_logged_in` (boolean): Indicates the customer was logged into their account when placing the order. - `cancel_reason` (string): A message describing the reason for cancelling the order, if applicable. - `canceled` (boolean): Indicates the order was completely canceled. - `comments` (string): Customer notes provided when placing the order, if any. - `coupon_id` (objectId): ID of the coupon applied to the order. - `date_canceled` (date): Date the order was canceled, if applicable. - `delivery_marked` (boolean): Indicates the order was marked as fulfilled, manually or automatically. - `discounts` (array of object): List of discounts applied to the order. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed discount amount. - `rule` (object): Object describing the discount rule details. Custom discounts don't require this value. - `type` (string): Type of discount. Can be `coupon` or `promo-` referring to the source of the discount. Custom discounts don't require this value. - `display_currency` (string): Three-letter ISO currency code representing the user's preferred display currency, if applicable. - `display_locale` (string): Locale code representing the user's preferred display locale, if applicable. - `gift_message` (string): Optional message to include with the order when shipping to the recipient. - `giftcards` (array of object): List of gift cards applied to the order. - `amount` (currency): Amount of the gift card balance to spend on this order. Defaults to `giftcard.balance`. - `code` (string): 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. - `id` (objectId): Unique identifier for the object. - `code_formatted` (string): Fully formatted gift card code for display purposes. - `last4` (string): Last four digits of the gift card code. - `giftcard` (giftcard): Expandable link to the gift card record. - `gift` (boolean): Indicates the order is intended as a gift for the recipient. - `guest` (boolean): Indicates the customer was not logged in when placing the order. Default: `{"$formula":"or(cart.guest, not(account_logged_in))"}`. - `hold` (boolean): Indicates the order was placed on hold. Default: `false`. - `item_tax_included` (boolean): Indicates line item prices include taxes. - `metadata` (object): Arbitrary data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for details. - `notes` (string): Internal admin notes, not visible to the customer. - `payment_marked` (boolean): Indicates the order was marked as paid, manually or automatically. - `promotion_ids` (array of child_scalar): List of promotion IDs applied to the order. - `shipment_discount` (currency): Shipping discount applied by [coupons](https://developers.swell.is/backend-api/coupons), [promotions](https://developers.swell.is/backend-api/promotions), or custom logic. - `shipment_tax` (currency): Shipping tax amount, if applicable. - `shipment_tax_included` (boolean): Indicates shipping total includes taxes, if applicable. - `taxes` (array of object): List of taxes applied to the order. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed tax amount. - `name` (string): Name of the tax rule. For example, "NY Sales Tax". - `priority` (int): 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. - `rate` (float): Tax percentage used in calculating the fixed amount. - `shipping` (boolean): Indicates the tax applies to shipping. - `account` (Account): Expandable link to the customer's account. - `authorized_payment_id` (string, auto): The id of an authorized payment. When "Require payment authorization" is enabled in payment settings, the order will be rejected if initial payment fails. - `authorized_payment` (Payment): Expandable link to an authorized payment. - `cart_id` (objectId, auto): ID of the cart that converted to this order, if applicable. - `cart` (Cart): Expandable link to the cart. - `coupon` (Coupon): Expandable link to the coupon applied to the order. - `credits` (Credit memo): Expandable list of account credit transactions. Balance of these transactions is kept in `balance`. - `credit_total` (currency): Total amount of additional credit applied to the order. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency. - `currency_rate` (float): Currency percentage used in calculating the fixed amount. - `date_payment_retry` (date): When automated payment has failed, this is the date when the system will automatically retry. - `date_period_end` (date, auto): Period end date applicable when the order was created from a `subscription`. - `date_period_start` (date, auto): Period start date applicable when the order was created from a `subscription`. - `date_webhook_first_failed` (date, auto): Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record. - `delivered` (boolean, auto): Indicates the order was completely fulfilled. Always `true` when `delivery_marked=true`, otherwise depends on the sum of `shipments`, `giftcards`, and `subscriptions`. Default: `false`. - `discount_total` (currency, auto): Total discount amount. - `giftcard_delivery` (boolean): Indicates the order has at least one line item with `delivery=giftcard`. - `giftcard_total` (currency): Total payment amount applied to the order from `giftcards`. - `grand_total` (currency, auto): Grand total including items, shipping and taxes. - `invoices` (Invoice): Expandable link to the invoice the payment was applied to, if applicable. - `item_discount` (currency, auto): Total discount applied to line items. - `item_quantity` (int, auto): Total quantity of all line items. - `item_quantity_cancelable` (int): Total quantity of cancelable items on the order. - `item_quantity_canceled` (int, auto): Total quantity of line items canceled. - `item_quantity_creditable` (int): Total quantity of line items that can be credited. - `item_quantity_credited` (int): Total quantity of items credited on the order. - `item_quantity_deliverable` (int, auto): Total quantity of line items that can be fulfilled. - `item_quantity_delivered` (int, auto): Total quantity of line items that have been fulfilled. - `item_quantity_giftcard_deliverable` (int, auto): Total quantity of line items that can be fulfilled by gift card. Applies when `item.delivery=giftcard`. - `item_quantity_invoiceable` (int): Total quantity of items eligible for invoicing on the order. - `item_quantity_invoiced` (int): Total quantity of items invoiced on the order. - `item_quantity_returnable` (int, auto): Total quantity of line items that can still be returned. - `item_quantity_returned` (int, auto): Total quantity of line items that have been returned. - `item_quantity_shipment_deliverable` (int, auto): Total quantity of line items that can be fulfilled by shipment. Applies when `item.delivery=shipment`. - `item_quantity_subscription_deliverable` (int, auto): Total quantity of line items that can be fulfilled by subscription. Applies when `item.delivery=subscription`. - `item_shipment_weight` (float): Total shipping weight of all line items. - `item_tax` (currency, auto): Total taxes applied to line items. - `notifications` (Notification): Expandable list of notifications sent on behalf of the order. - `number` (string, auto): Unique incremental order number, assigned automatically using a format configured in general settings. - `paid` (boolean, auto): Indicates the order was paid in full. Always `true` when `payment_marked=true`, otherwise depends on the sum of `payments`. Default: `false`. - `parent` (Order): Expandable link to the parent order. - `parent_id` (objectId): ID of the parent order. - `payments` (Payment): Expandable list of payments applied to the order. - `payment_balance` (currency, auto): 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. - `payment_error` (string): A message describing the last payment error, if one occurred. - `payment_retry_count` (int): The number of times automatic payment has been attempted. - `payment_retry_resolve` (string): The method used to resolve automatic payment when all retry attempts are exhausted. Can be blank (do nothing), `canceled`, or `unpaid`. - `payment_total` (currency): Sum of payments applied to the order, not including refunds. Default: `0`. - `pending_invoices` (Invoice): Expandable list of invoices that haven't been fully paid. - `promotions` (Promotion): Expandable list of promotions applied to the order. - `refund_marked` (boolean): Indicates the order was marked as refunded, manually or automatically. - `refund_total` (currency): Sum of refunds on payments applied to the order. Default: `0`. - `refunded` (boolean, auto): Indicates the order was fully refunded. Always `true` when `refund_marked=true`, otherwise depends on the sum of `refunds`. Default: `false`. - `refunds` (Refund): Expandable list of refunds applied to the order. - `return_credit_tax` (currency): Total additional credit tax applied to the order from returns, if applicable - `return_credit_total` (currency): Total additional credit amount applied to the order from returns. - `return_item_tax` (currency, auto): Total tax amount of items returned. - `return_item_tax_included` (currency, auto): Total tax included amount of items returned, separate from line item values. - `return_item_total` (currency, auto): Total amount of items returned, minus discounts. - `return_total` (currency): Grand total amount applied to the order from returns. - `shipment_delivery` (boolean): Indicates the order has at least one line item with `delivery=shipment`. - `shipment_price` (currency, auto): Total shipping price before discounts. - `shipment_rating` (object, auto): Object describing the shipping services and rates available for the order. Shipping `country` must be set before retrieving shipping rates. - `errors` (array of object): List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here. - `code` (string): Unique code describing the error. - `message` (string): Message describing the error. - `fingerprint` (string): Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings. - `services` (array of object): List of shipping services and rates available. - `id` (string): Unique identifier for the object. - `carrier` (string): Name of a third-party carrier offering the service, if applicable. - `name` (string): Name of the shipping service. - `price` (currency): Price of the shipping service. - `pickup` (boolean): Indicates whether shipping service is local pick-up. - `shipment_tax_included_total` (currency, auto): Total shipping price including taxes and discount. Allows for an alternate display style as normally `shipment_total` and `tax_total` are shown separately. - `shipment_total` (currency, auto): Total shipping price after discounts. - `shipments` (Shipment): Expandable list of shipments created from the order. - `status` (enum, auto): Current status of the order. Can be `pending`, `draft`, `payment_pending`, `delivery_pending`, `hold`, `complete`, or `canceled`. Possible values: `pending`, `draft`, `payment_pending`, `delivery_pending`, `hold`, `complete`, `canceled`. Default: `"pending"`. - `sub_total` (currency, auto): Sum of all line items before discounts, taxes and shipping. - `subscription_delivery` (boolean): Indicates the order has at least one line item with `delivery=subscription`. - `subscription_id` (objectId, auto): ID of the subscription that spawned the order, if applicable. - `subscription` (Subscription): Expandable link to the subscription that spawned the order, if applicable. - `tax_included_total` (currency, auto): Total of taxes applied separately from line items. - `tax_total` (currency, auto): Total tax amount applied to the order including line items and shipping. - `webhook_attempts_failed` (int, auto): Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_response` (string, auto): Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_status` (int, auto): 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. - `taxes_fixed` (boolean): Indicates the order is tax-exempt. Taxes will not be calculated or applied when true. - `draft` (boolean): 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](https://developers.swell.is/backend-api/carts/the-cart-model) for details. - `test` (boolean): Indicates the order was made in test mode. - `closed` (boolean): Indicates the order is closed. Default: `false`. - `shipment_total_credited` (currency): Total shipping price for items credited on the order. - `prev_id` (objectId): This never gets set by Swell. A customer must explicitly set this field to a particular order ID. - `prev` (Order): If `prev_id` is set by the customer, `prev` will link to the order with the given `prev_id`. - `next_id` (objectId): This never gets set by Swell. A customer must explicitly set this field to a particular order ID. - `next` (Order): If `next_id` is set by the customer, `next` will link to the order with the given `next_id`. - `account_credit_applied` (boolean): Indicates the customer’s account credit is applied when submitting the order. - `date_webhook_last_succeeded` (date): Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record. - `date_scheduled` (date): Scheduled date for the order. ### Example request `POST /orders` **cURL** ```bash $ curl https://api.swell.store/orders \ -u store-id:secret-key \ -d account_id=5a9ea7ba3f95740a914267f1 \ -d items[0][product_id]=5cad15bc9b14d1990724663a \ -d items[0][quantity]=2 \ -d coupon_code=FREESHIPPING ``` **Node** ```javascript 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', }); ``` **PHP** ```php post('/orders', [ 'items' => [ [ 'product_id' => '5cad15bc9b14d1990724663a', 'quantity' => 2, ] ], 'account_id' => '5a9ea7ba3f95740a914267f1', 'billing' => [ ... ], 'shipping' => [ ... ], 'coupon_code' => 'FREESHIPPING', ]); ``` ### Example response ```json { "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, ... } ``` ## Retrieve an order Retrieve an existing order using the ID that was returned when created. ### Arguments - `id` (objectId, required): The id of the order to retrieve. - `expand` (string): Expanding link fields and child collections is performed using the expand argument. - For example, `expand=account` would return a related customer account if one exists. When the field represents a collection, you can specify the query limit. - For example, `expand=variants:10` would return up to 10 records of the variants collection. See [expanding ](https://developers.swell.is/backend-api/querying/expanding)for more details. - `fields` (string): Return only the specified fields in the result. For example `fields=name,slug` would return only the fields `name` and `slug` in the response. Supports nested object and array fields using dot-notation, for example, `items.product_id`. The category `id` is always returned. - `include` (string): Include one or more arbitrary queries in the response, possibly related to the main query. See [including ](https://developers.swell.is/backend-api/querying/including)for more details. ### Example request `GET /orders/:id` **cURL** ```bash $ curl https://api.swell.store/orders/5cad15bc9b14d1990724663a \ -u store-id:secret-key ``` **Node** ```javascript const { swell } = require('swell-node'); swell.init('store-id', 'secret-key'); await swell.get('/orders/{id}', { id: '5cad15bc9b14d1990724663a', }); ``` **PHP** ```php get('/orders/{id}', [ 'id' => '5cad15bc9b14d1990724663a', ]); ``` ### Example response ```json { "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, ... } ``` ## Update an order Update an existing order using the ID that was returned when created. Updating performs a merge operation. To explicitly override values such as arrays, use the `$set` operator. ### Arguments - `id` (objectId, required): Unique identifier for the order. - `account_id` (objectId, required): ID of the customer's account. - `account` (Account): Expandable link to the customer's account. - `account_credit_amount` (currency): Amount of customer's account credit applied for initial payment, if applicable. - `account_credit_applied` (boolean): Indicates the customer’s account credit is applied when submitting the order. - `account_info_saved` (boolean): Indicates the customer chose to save shipping and billing information to their account when submitting the order. - `account_logged_in` (boolean): Indicates the customer was logged into their account when placing the order. - `authorized_payment` (Payment): Expandable link to an authorized payment. - `authorized_payment_id` (string, auto): The id of an authorized payment. When "Require payment authorization" is enabled in payment settings, the order will be rejected if initial payment fails. - `billing` (object): The customer's billing details. Defaults to `account.billing`. Updating billing will also update the corresponding account billing object. - `account_card_id` (objectId): ID of the customer's credit card on file, if applicable. - `account_card` (account_card): Expandable link to the customer's credit card on file, if applicable. - `address1` (string): Billing address line 1: street address/PO box/company name. - `address2` (string): Billing address line 2: apartment/suite/unit/building. - `amazon` (object): Amazon billing details used when `billing.method=amazon`. - `access_token` (string): Amazon access token provided when a customer authorizes payment in a storefront. - `order_reference_id` (string): Amazon order reference ID created when a customer initiates payment in a storefront. - `checkout_session_id` (string) - `card` (object): Credit card billing details used when `billing.method=card`. - `token` (string): Token generated by Swell Checkout or [Stripe.js](https://stripe.com/docs/stripe-js/reference). - `exp_month` (int): Two-digit number representing the credit card expiration month. - `exp_year` (int): Four-digit number representing the credit card expiration year. - `brand` (string): Credit card brand. Can be `American Express`, `Diners Club`, `Discover`, `JCB`, `MasterCard`, `UnionPay`, `Visa`, or `Unknown`. - `last4` (string): Last four digits of the card number. - `gateway` (string): ID of the payment gateway that should be used to process payments. - `test` (boolean): Indicates this is a test card. - `address_check` (string): When used with a payment gateway that performs address checks and `address1` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `zip_check` (string): When used with a payment gateway that performs address checks and `zip` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `cvc_check` (string): When used with a payment gateway that performs CVC code checks and `cvc` was provided, can be `pass`, `fail`, `unavailable`, or `unchecked`. - `city` (string): Billing city/district/suburb/town/village. - `country` (string): Two-letter ISO code country code. - `first_name` (string): Billing first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Billing last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `method` (string): Method of payment. Can be `card`, `account`, `amazon`, `paypal`, or any one of the manual methods defined in payment settings. - `name` (string): Billing full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `paypal` (object): PayPal billing details used when `billing.method=paypal`. - `payer_id` (string): PayPal payer ID provided when a customer authorizes payment in a storefront. - `payment_id` (string): PayPal payment ID created when a customer initiates payment in a storefront. - `order_id` (string) - `phone` (string): Billing phone number. - `state` (string): Billing state/county/province/region. - `zip` (string): Billing zip/postal code. - `default` (boolean): Indicates billing details represent the customer's default payment method. - `intent` (object): Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized. - `affirm` (object): Affirm billing details used when `billing.method=affirm`. - `checkout_token` (string): Token used to communicate payment information to the gateway. - `resolve` (object): Resolve billing details used when `billing.method=resolve`. - `charge_id` (string): Charge ID returned by the payment gateway for the payment. - `ideal` (object): Ideal billing details used when `billing.method=ideal`. - `token` (string): Token used to communicate payment information to the gateway. - `google` (object): Google Pay billing details used when `billing.method=google`. - `nonce` (string): One-time use reference element used to communicate payment information to a payment gateway. - `gateway` (string): Gateway used to facilitate the transaction. For example, Braintree. - `apple` (object): Apple Pay billing details used when `billing.method=apple`. - `nonce` (string): One-time use reference element used to communicate payment information to a payment gateway. - `gateway` (string): Gateway used to facilitate the transaction. For example, Braintree. - `instructions` (string) - `cancel_reason` (string): A message describing the reason for cancelling the order, if applicable. - `canceled` (boolean): Indicates the order was completely canceled. - `cart` (Cart): Expandable link to the cart. - `cart_id` (objectId, auto): ID of the cart that converted to this order, if applicable. - `closed` (boolean): Indicates the order is closed. Default: `false`. - `comments` (string): Customer notes provided when placing the order, if any. - `coupon` (Coupon): Expandable link to the coupon applied to the order. - `coupon_code` (string): Coupon code applied to the order. See [coupons](https://developers.swell.is/backend-api/coupons) for details. - `coupon_id` (objectId): ID of the coupon applied to the order. - `credit_total` (currency): Total amount of additional credit applied to the order. - `credits` (Credit memo): Expandable list of account credit transactions. Balance of these transactions is kept in `balance`. - `currency` (string): Three-letter ISO currency code in uppercase. Defaults to the store's base currency. - `currency_rate` (float): Currency percentage used in calculating the fixed amount. - `date_canceled` (date): Date the order was canceled, if applicable. - `date_payment_retry` (date): When automated payment has failed, this is the date when the system will automatically retry. - `date_period_end` (date, auto): Period end date applicable when the order was created from a `subscription`. - `date_period_start` (date, auto): Period start date applicable when the order was created from a `subscription`. - `date_scheduled` (date): Scheduled date for the order. - `date_webhook_first_failed` (date, auto): Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record. - `date_webhook_last_succeeded` (date): Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record. - `delivered` (boolean, auto): Indicates the order was completely fulfilled. Always `true` when `delivery_marked=true`, otherwise depends on the sum of `shipments`, `giftcards`, and `subscriptions`. Default: `false`. - `delivery_marked` (boolean): Indicates the order was marked as fulfilled, manually or automatically. - `discount_total` (currency, auto): Total discount amount. - `discounts` (array of object): List of discounts applied to the order. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed discount amount. - `rule` (object): Object describing the discount rule details. Custom discounts don't require this value. - `type` (string): Type of discount. Can be `coupon` or `promo-` referring to the source of the discount. Custom discounts don't require this value. - `display_currency` (string): Three-letter ISO currency code representing the user's preferred display currency, if applicable. - `display_locale` (string): Locale code representing the user's preferred display locale, if applicable. - `draft` (boolean): 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](https://developers.swell.is/backend-api/carts/the-cart-model) for details. - `gift` (boolean): Indicates the order is intended as a gift for the recipient. - `gift_message` (string): Optional message to include with the order when shipping to the recipient. - `giftcard_delivery` (boolean): Indicates the order has at least one line item with `delivery=giftcard`. - `giftcard_total` (currency): Total payment amount applied to the order from `giftcards`. - `giftcards` (array of object): List of gift cards applied to the order. - `amount` (currency): Amount of the gift card balance to spend on this order. Defaults to `giftcard.balance`. - `code` (string): 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. - `id` (objectId): Unique identifier for the object. - `code_formatted` (string): Fully formatted gift card code for display purposes. - `last4` (string): Last four digits of the gift card code. - `giftcard` (giftcard): Expandable link to the gift card record. - `grand_total` (currency, auto): Grand total including items, shipping and taxes. - `guest` (boolean): Indicates the customer was not logged in when placing the order. Default: `{"$formula":"or(cart.guest, not(account_logged_in))"}`. - `hold` (boolean): Indicates the order was placed on hold. Default: `false`. - `invoices` (Invoice): Expandable link to the invoice the payment was applied to, if applicable. - `item_discount` (currency, auto): Total discount applied to line items. - `item_quantity` (int, auto): Total quantity of all line items. - `item_quantity_cancelable` (int): Total quantity of cancelable items on the order. - `item_quantity_canceled` (int, auto): Total quantity of line items canceled. - `item_quantity_creditable` (int): Total quantity of line items that can be credited. - `item_quantity_credited` (int): Total quantity of items credited on the order. - `item_quantity_deliverable` (int, auto): Total quantity of line items that can be fulfilled. - `item_quantity_delivered` (int, auto): Total quantity of line items that have been fulfilled. - `item_quantity_giftcard_deliverable` (int, auto): Total quantity of line items that can be fulfilled by gift card. Applies when `item.delivery=giftcard`. - `item_quantity_invoiceable` (int): Total quantity of items eligible for invoicing on the order. - `item_quantity_invoiced` (int): Total quantity of items invoiced on the order. - `item_quantity_returnable` (int, auto): Total quantity of line items that can still be returned. - `item_quantity_returned` (int, auto): Total quantity of line items that have been returned. - `item_quantity_shipment_deliverable` (int, auto): Total quantity of line items that can be fulfilled by shipment. Applies when `item.delivery=shipment`. - `item_quantity_subscription_deliverable` (int, auto): Total quantity of line items that can be fulfilled by subscription. Applies when `item.delivery=subscription`. - `item_shipment_weight` (float): Total shipping weight of all line items. - `item_tax` (currency, auto): Total taxes applied to line items. - `item_tax_included` (boolean): Indicates line item prices include taxes. - `items` (array of object): List of line items describing the products ordered. - `bundle_items` (array of object): List of items offered as a bundle. Defaults to `product.bundle_items`. - `product_id` (objectId, required): ID of the bundle item product. - `product` (product): Expandable link to the bundle item product. - `quantity` (int): Quantity of the bundle item being ordered. Defaults to 1. Default: `1`. - `shipment_weight` (float): Weight to be used in shipping calculation, if applicable. - `quantity_restocked` (int): Quantity of the bundle item that has been restocked after a return, if applicable. - `quantity_returnable` (int): Quantity of the bundle item that can still be returned after fulfillment, if applicable. - `variant_id` (objectId): ID of the bundle item variant. - `variant` (variant): Expandable link to the bundle item product variant. - `id` (objectId, auto): Unique identifier for the object. - `delivery` (enum): Method of delivery taken automatically from `product.delivery`. Possible values: `shipment`, `giftcard`, `subscription`. - `options` (array of object): 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. - `id` (string): Unique identifier for the object. - `name` (string): Name of the product option. Populated automatically when adding an option by ID. - `price` (currency): Additional price added onto the base price of the product. - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product. - `value` (string): 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. - `variant` (boolean): Indicates the option refers to a variant aspect. - `value_id` (objectId) - `quantity_canceled` (int): Quantity of the bundle item canceled before fulfillment, if applicable. Default: `0`. - `quantity_consumed` (int): Quantity of stock consumed by the bundle item, if applicable. - `quantity_deliverable` (int): Quantity of the bundle item that can be fulfilled, if applicable. - `quantity_delivered` (int): Quantity of the bundle item that has been fulfilled, if applicable. Default: `0`. - `quantity_giftcard_deliverable` (int): Quantity of the bundle item that can be fulfilled by a gift card. Applies when `delivery=giftcard`. - `quantity_returned` (int): Total quantity of bundle items that have been returned. - `quantity_shipment_deliverable` (int): Quantity of the bundle item that can be fulfilled by a shipment. Applies when `delivery=shipment`. - `quantity_total` (int): Total quantity of the bundle item to be fulfilled, calculated as `item.quantity * bundle_item.quantity`. - `stock_tracking` (boolean): Indicates whether the bundle item has stock tracking enabled. - `quantity_shipment_delivered` (int): Quantity of shipments that have been delivered. - `product_name` (string): This field is a copy of the item's `product.name`. Default: `{"$formula":"if(product_id, product.name, null)"}`. - `description` (string): Description used for custom line items, when product is not defined. - `discounts` (array of object): List of discounts to apply to the item. Normally populated by applying a [coupon](https://developers.swell.is/backend-api/coupons/the-coupon-model) or [promotions.](https://developers.swell.is/backend-api/promotions/the-promotion-model) - `id` (string, required): Unique identifier for the object. Should refer to one of the IDs in the order `discounts` object. - `amount` (currency, required): Fixed discount amount. - `metadata` (object): Arbitrary item data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for details. - `options` (array of object): 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. - `id` (string): Unique identifier for the object. - `name` (string): Name of the product option. Populated automatically when adding an option by ID. - `price` (currency): Additional price added onto the base price of the product. - `shipment_weight` (float): Additional shipping weight added onto the base weight of the product. - `variant` (boolean): Indicates the option refers to a variant aspect. - `value` (string): 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. - `value_id` (objectId): ID associate to the value. - `price` (currency): Price of the item. Override this value to set a custom price. Defaults to product price or sale price. Default: `{"$formula":"if(product_id, product.price)"}`. - `product_id` (objectId): ID of the item product. - `quantity` (int): Quantity of the item being ordered. Defaults to 1. Default: `1`. - `quantity_restocked` (int): Quantity of the item that has been restocked after a return, if applicable. - `quantity_returnable` (int): Quantity of the item that can still be returned after fulfillment, if applicable. - `quantity_returned` (int): Quantity of the item that has been returned after fulfillment, if applicable. - `shipment_weight` (float): Weight to be used in shipping calculation, if applicable. - `taxes` (array of object): List of tax rules to apply to the item. Normally populated by tax settings. - `id` (string, required): Unique identifier for the object. Should refer to one of the IDs in the order `taxes` object. - `amount` (currency, required): Fixed tax amount. - `variant_id` (objectId): ID of the item variant, if applicable. - `id` (objectId, auto): Unique identifier for the item. - `delivery` (enum): Method of delivery taken automatically from `product.delivery`. Possible values: `shipment`, `giftcard`, `subscription`. - `discount_each` (currency): Total discount amount divided by quantity. - `discount_total` (currency): Total discount applied to the item. - `orig_price` (currency): Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed. - `price_total` (currency): Total price added to sub total by multiplying `quantity` and `price`. - `product` (product): Expandable link to the item product. - `product_name` (string): Name of the product. Default: `{"$formula":"if(product_id, product.name, null)"}`. - `quantity_canceled` (int): Quantity of the item canceled before fulfillment, if applicable. Default: `0`. - `quantity_consumed` (int): Quantity of stock consumed by the item, if applicable. - `quantity_deliverable` (int): Quantity of the item that can be fulfilled, if applicable. - `quantity_delivered` (int): Quantity of the item that has been fulfilled, if applicable. Default: `0`. - `quantity_giftcard_deliverable` (int): Quantity of the item that can be fulfilled by a gift card. Applies when `delivery=giftcard`. - `quantity_shipment_deliverable` (int): Quantity of the item that can be fulfilled by a shipment. Applies when `delivery=shipment`. - `quantity_subscription_deliverable` (int): Quantity of the item that can be fulfilled by a subscription. Applies when `delivery=subscription`. - `shipment_location` (string): ID of location from `/settings/shipping/locations`. If specified, shipping is calculated from this location. Otherwise, the store's default location will be used. - `stock_tracking` (boolean): Indicates whether the item has stock tracking enabled. - `subscription_paid` (boolean): Indicates the item has been fulfilled as a [subscription](https://developers.swell.is/backend-api/subscriptions/the-subscription-model) and marked as `paid by reference to this order.` - `tax_each` (currency): Total tax amount divided by quantity. - `tax_total` (currency): Total tax applied to the item. - `variant` (variant): Expandable link to the item variant, if applicable. - `metadata` (object): Arbitrary data, typically set in a checkout flow to store custom values. See [Storefront API](https://developers.swell.is/frontend-api/introduction) for details. - `next` (Order): If `next_id` is set by the customer, `next` will link to the order with the given `next_id`. - `next_id` (objectId): This never gets set by Swell. A customer must explicitly set this field to a particular order ID. - `notes` (string): Internal admin notes, not visible to the customer. - `notifications` (Notification): Expandable list of notifications sent on behalf of the order. - `number` (string, auto): Unique incremental order number, assigned automatically using a format configured in general settings. - `paid` (boolean, auto): Indicates the order was paid in full. Always `true` when `payment_marked=true`, otherwise depends on the sum of `payments`. Default: `false`. - `parent` (Order): Expandable link to the parent order. - `parent_id` (objectId): ID of the parent order. - `payment_balance` (currency, auto): 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. - `payment_error` (string): A message describing the last payment error, if one occurred. - `payment_marked` (boolean): Indicates the order was marked as paid, manually or automatically. - `payment_retry_count` (int): The number of times automatic payment has been attempted. - `payment_retry_resolve` (string): The method used to resolve automatic payment when all retry attempts are exhausted. Can be blank (do nothing), `canceled`, or `unpaid`. - `payment_total` (currency): Sum of payments applied to the order, not including refunds. Default: `0`. - `payments` (Payment): Expandable list of payments applied to the order. - `pending_invoices` (Invoice): Expandable list of invoices that haven't been fully paid. - `prev` (Order): If `prev_id` is set by the customer, `prev` will link to the order with the given `prev_id`. - `prev_id` (objectId): This never gets set by Swell. A customer must explicitly set this field to a particular order ID. - `promotion_ids` (array of child_scalar): List of promotion IDs applied to the order. - `promotions` (Promotion): Expandable list of promotions applied to the order. - `refund_marked` (boolean): Set `true` mark the order as fully refunded, regardless of refund records. - `refund_total` (currency): Sum of refunds on payments applied to the order. Default: `0`. - `refunded` (boolean, auto): Indicates the order was fully refunded. Always `true` when `refund_marked=true`, otherwise depends on the sum of `refunds`. Default: `false`. - `refunds` (Refund): Expandable list of refunds applied to the order. - `return_credit_tax` (currency): Total additional credit tax applied to the order from returns, if applicable - `return_credit_total` (currency): Total additional credit amount applied to the order from returns. - `return_item_tax` (currency, auto): Total tax amount of items returned. - `return_item_tax_included` (currency, auto): Total tax included amount of items returned, separate from line item values. - `return_item_total` (currency, auto): Total amount of items returned, minus discounts. - `return_total` (currency): Grand total amount applied to the order from returns. - `shipment_delivery` (boolean): Indicates the order has at least one line item with `delivery=shipment`. - `shipment_discount` (currency): Shipping discount applied by [coupons](https://developers.swell.is/backend-api/coupons), [promotions](https://developers.swell.is/backend-api/promotions), or custom logic. - `shipment_price` (currency, auto): Total shipping price before discounts. - `shipment_rating` (object, auto): Object describing the shipping services and rates available for the order. Shipping `country` must be set before retrieving shipping rates. - `errors` (array of object): List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here. - `code` (string): Unique code describing the error. - `message` (string): Message describing the error. - `fingerprint` (string): Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings. - `services` (array of object): List of shipping services and rates available. - `id` (string): Unique identifier for the object. - `carrier` (string): Name of a third-party carrier offering the service, if applicable. - `name` (string): Name of the shipping service. - `price` (currency): Price of the shipping service. - `pickup` (boolean): Indicates whether shipping service is local pick-up. - `shipment_tax` (currency): Shipping tax amount, if applicable. - `shipment_tax_included` (boolean): Indicates shipping total includes taxes, if applicable. - `shipment_tax_included_total` (currency, auto): Total shipping price including taxes and discount. Allows for an alternate display style as normally `shipment_total` and `tax_total` are shown separately. - `shipment_total` (currency, auto): Total shipping price after discounts. - `shipment_total_credited` (currency): Total shipping price for items credited on the order. - `shipments` (Shipment): Expandable list of shipments created from the order. - `shipping` (object): The customer's shipping details. Defaults to `account.shipping`. Updating shipping will also update the corresponding account shipping object. - `account_address_id` (objectId): ID of the customer's address on file. - `account_address` (account_address): Expandable link to the customer's address on file. - `address1` (string): Shipping address line 1: street address/PO box/company name. - `address2` (string): Shipping address line 2: apartment/suite/unit/building. - `city` (string): Shipping city/district/suburb/town/village. - `country` (string): Two-letter ISO country code. - `default` (boolean): Indicates shipping details represent the customer's default shipping address. - `first_name` (string): Shipping first name. If `name` is updated, then `first_name` will be automatically updated as the first word of the name. - `last_name` (string): Shipping last name. If `name` is updated, then `last_name` will be automatically updated as the last words of the name. - `name` (string): Shipping full name. If `first_name` or `last_name` are updated, then `name` will be automatically updated as a combination of first/last. - `phone` (string): Shipping phone number. - `price` (currency): Price of the shipping service. Defaults to `shipment_rating.services.price` chosen by setting `service`. - `service` (string): ID of a shipping service as configured in shipment settings. Normally, this would be applied after [retrieving shipping rates](https://developers.swell.is/backend-api/shipments/retrieve-a-shipment) by using one of the `shipment_rating.services.id` values. - `service_name` (string): Name of the shipping service. Defaults to `shipment_rating.services.name` chosen by setting `service`. - `state` (string): Shipping state/county/province/region. - `zip` (string): Shipping zip/postal code. - `pickup` (boolean): Indicates whether shipping for local pick-up. - `status` (enum, auto): Current status of the order. Can be `pending`, `draft`, `payment_pending`, `delivery_pending`, `hold`, `complete`, or `canceled`. Possible values: `pending`, `draft`, `payment_pending`, `delivery_pending`, `hold`, `complete`, `canceled`. Default: `"pending"`. - `sub_total` (currency, auto): Sum of all line items before discounts, taxes and shipping. - `subscription` (Subscription): Expandable link to the subscription that spawned the order, if applicable. - `subscription_delivery` (boolean): Indicates the order has at least one line item with `delivery=subscription`. - `subscription_id` (objectId, auto): ID of the subscription that spawned the order, if applicable. - `tax_included_total` (currency, auto): Total of taxes applied separately from line items. - `tax_total` (currency, auto): Total tax amount applied to the order including line items and shipping. - `taxes` (array of object): List of taxes applied to the order. - `id` (string): Unique identifier for the object. - `amount` (currency): Fixed tax amount. - `name` (string): Name of the tax rule. For example, "NY Sales Tax". - `priority` (int): 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. - `rate` (float): Tax percentage used in calculating the fixed amount. - `shipping` (boolean): Indicates the tax applies to shipping. - `taxes_fixed` (boolean): Indicates the order is tax-exempt. Taxes will not be calculated or applied when true. - `test` (boolean): Indicates the order was made in test mode. - `webhook_attempts_failed` (int, auto): Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_response` (string, auto): Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record. - `webhook_status` (int, auto): 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. ### Example request `PUT /orders/:id` **cURL** ```bash $ curl https://api.swell.store/orders/5cad15bc9b14d1990724663a \ -u store-id:secret-key \ -d name="Jon Snow" \ -d address1="1 Main Street" \ -d city=Brooklyn \ -d state=NY \ -d zip=11201 \ -d country=US \ -d phone="(555) 555-5555" \ -X PUT ``` **Node** ```javascript const { swell } = require('swell-node'); swell.init('store-id', 'secret-key'); await swell.put('/orders/{id}', { id: '5cad15bc9b14d1990724663a', shipping: { name: 'Jon Snow', address1: '1 Main Street', city: 'Brooklyn', state: 'NY', zip: '11201', country: 'US', phone: '(555) 555-5555', }, }); ``` **PHP** ```php put('/orders/{id}', [ 'id' => '5cad15bc9b14d1990724663a', 'shipping' => [ 'name' => 'Jon Snow', 'address1' => '1 Main Street', 'city' => 'Brooklyn', 'state' => 'NY', 'zip' => '11201', 'country' => 'US', 'phone' => '(555) 555-5555' ] ]); ``` ### Example response ```json { "id": "5cad15bc9b14d1990724663a", "account_id": "5a9ea7ba3f95740a914267f1", "billing": {...}, "shipping": { "name": "Jon Snow", "first_name": "Jon", "last_name": "Snow", "address1": "1 Main Street", "city": "Brooklyn", "state": "NY", "zip": "11201", "country": "US", "phone": "(555) 555-5555" }, "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", "date_updated": "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, ... } ``` ## List all orders Return a list of orders. ### Arguments - `expand` (string): Expand link fields and child collections by using the expand argument. - For example, `expand=account` would return a related customer account if one exists. When the field represents a collection, you can specify the query limit. - For example, `expand=variants:10` would return up to 10 records of the variants collection. See [expanding](https://developers.swell.is/backend-api/querying/expanding) for more details. - `fields` (string): Returns only the specified fields in the result. - For example `fields=name,slug` would return only the fields `name` and `slug` in the response. Supports nested object and array fields using dot-notation. - For example, `items.product_id`. The product `id` is always returned. - `include` (object): Include one or more arbitrary queries in the response which are potentially related to the main query. See [including](https://developers.swell.is/backend-api/querying/including) for more details. - `limit` (int): Limit the number of records returned, ranging between `1` and `1000`. Defaults to `15`. Default: `15`. - `page` (int): The page number of results to return given the specified or default `limit`. - `search` (string): A text search is performed using the search argument. Searchable fields are defined by the model. - For example, `search=red` would return records containing the word "red" anywhere in the defined text fields. See [searching](https://developers.swell.is/backend-api/querying/searching) for more details. - `sort` (string): Expression to sort results by using a format similar to a SQL sort statement. - For example, `sort=name asc` would return records sorted by name ascending. See [sorting](https://developers.swell.is/backend-api/querying/sorting) for more details. - `where` (object): An object with criteria to filter the result. - For example, `active=true` would return records containing a field `active` with the value `true`. It's also possible to use query operators, for example, `$eq`, `$ne`, `$gt`, and more. See [querying](https://developers.swell.is/backend-api/querying) for more details. ### Example request `GET /orders` **cURL** ```bash $ curl https://api.swell.store/orders?where[account_id]=592ef41c57ce232e1ce3729e&limit=25&page=1 \ -u store-id:secret-key \ -G ``` **Node** ```javascript const { swell } = require('swell-node'); swell.init('store-id', 'secret-key'); await swell.get('/orders', { where: { account_id: '592ef41c57ce232e1ce3729e', }, limit: 25, page: 1, }); ``` **PHP** ```php get('/orders', [ 'where' => [ 'account_id' => '592ef41c57ce232e1ce3729e' ], 'limit' => 25, 'page' => 1, ]); ``` ### Example response ```json { "count": 51, "results": [ { "id": "5cad15bc9b14d1990724663a", "account_id": "5a9ea7ba3f95740a914267f1", "billing": {...}, "shipping": { "name": "Jon Snow", "first_name": "Jon", "last_name": "Snow", "address1": "1 Main Street", "city": "Brooklyn", "state": "NY", "zip": "11201", "country": "US", "phone": "(555) 555-5555" }, "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", "date_updated": "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, ... }, {...}, {...} ], "page": 1, "page_count": 3, "limit": 25, "pages": { "1": { "start": 1, "end": 25 }, "2": { "start": 26, "end": 50 }, "3": { "start": 51, "end": 51 } } } ``` ## Delete an order Delete an order permanently. ### Arguments - `id` (objectId, required): The id of the order to delete. ### Example request `DELETE /orders/:id` **cURL** ```bash $ curl https://api.swell.store/orders/5cad15bc9b14d1990724663a \ -u store-id:secret-key \ -X DELETE ``` **Node** ```javascript const { swell } = require('swell-node'); swell.init('store-id', 'secret-key'); await swell.delete('/orders/{id}', { id: '5cad15bc9b14d1990724663a', }); ``` **PHP** ```php delete('/orders/{id}', [ 'id' => '5cad15bc9b14d1990724663a', ]); ``` ### Example response ```json { "id": "5cad15bc9b14d1990724663a", "account_id": "5a9ea7ba3f95740a914267f1", "billing": {...}, "shipping": { "name": "Jon Snow", "first_name": "Jon", "last_name": "Snow", "address1": "1 Main Street", "city": "Brooklyn", "state": "NY", "zip": "11201", "country": "US", "phone": "(555) 555-5555" }, "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", "date_updated": "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, ... } ```