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 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

objectIdrequired

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

stringauto

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.

billing.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.

billing.first_name

stringrequired

Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.

billing.last_name

stringrequired

Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.

billing.address1

string

Billing address line 1: street address/PO box/company name.

billing.address2

string

Billing address line 2: apartment/suite/unit/building.

billing.city

string

Billing city/district/suburb/town/village.

billing.state

string

Billing state/county/province/region.

billing.zip

string

Billing zip/postal code.

billing.country

string

Two-letter ISO country code.

billing.phone

string

Billing phone number.

billing.method

string

Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.

billing.card

object

Credit card billing details used when billing.method=card.

billing.default

boolean

Indicates billing details represent the customer's default payment method.

billing.account_card_id

objectId

ID of the customer's credit card on file, if applicable.

billing.account_card

account_card

Expandable link to the customer's credit card on file, if applicable.

billing.amazon

object

Amazon billing details used when billing.method=amazon.

billing.paypal

object

PayPal billing details used when billing.method=paypal.

billing.intent

object

Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.

billing.affirm

object

Affirm billing details used when billing.method=affirm.

billing.resolve

object

Resolve billing details used when billing.method=resolve.

billing.klarna

object

Klarna billing details used when billing.method=klarna.

billing.ideal

object

Ideal billing details used when billing.method=ideal.

billing.bancontact

object

Bancontact billing details used when billing.method=bancontact.

billing.google

object

Google Pay billing details used when billing.method=google.

billing.apple

object

Apple Pay billing details used when billing.method=apple.

billing.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

objectIdauto

ID of the cart that converted to this order, if applicable.

closed

boolean

Indicates the order is closed.

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.

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_created

dateauto

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

dateauto

Period end date applicable when the order was created from a subscription.

date_period_start

dateauto

Period start date applicable when the order was created from a subscription.

date_scheduled

date

Scheduled date for the order.

date_updated

dateauto

Date and time the order was last updated.

date_webhook_first_failed

dateauto

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

booleanauto

Indicates the order was completely fulfilled. Always true when delivery_marked=true, otherwise depends on the sum of shipments, giftcards, and subscriptions.

delivery_marked

boolean

Indicates the order was marked as fulfilled, manually or automatically.

discount_total

currencyauto

Total discount amount.

discounts

array of object

List of discounts applied to the order.

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.

grand_total

currencyauto

Grand total including items, shipping and taxes.

guest

boolean

Indicates the customer was not logged in when placing the order.

hold

boolean

Indicates the order was placed on hold.

invoices

Invoice

Expandable link to the invoice the payment was applied to, if applicable.

item_discount

currencyauto

Total discount applied to line items.

item_quantity

intauto

Total quantity of all line items.

item_quantity_cancelable

int

Total quantity of cancelable items on the order.

item_quantity_canceled

intauto

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

intauto

Total quantity of line items that can be fulfilled.

item_quantity_delivered

intauto

Total quantity of line items that have been fulfilled.

item_quantity_giftcard_deliverable

intauto

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

intauto

Total quantity of line items that can still be returned.

item_quantity_returned

intauto

Total quantity of line items that have been returned.

item_quantity_shipment_deliverable

intauto

Total quantity of line items that can be fulfilled by shipment. Applies when item.delivery=shipment.

item_quantity_subscription_deliverable

intauto

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

currencyauto

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.

id

objectIdauto

Unique identifier for the item.

bundle_items

array of object

List of items offered as a bundle. Defaults to product.bundle_items.

id

objectIdauto

Unique identifier for the object.

product_id

objectIdrequired

ID of the bundle item product.

delivery

enum

Method of delivery taken automatically from product.delivery.

Possible enum values:

shipmentgiftcardsubscription

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.

product

Expandable link to the bundle item product.

quantity

int

Quantity of the bundle item being ordered. Defaults to 1.

quantity_canceled

int

Quantity of the bundle item canceled before fulfillment, if applicable.

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.

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.

stock_tracking

boolean

Indicates whether the bundle item has stock tracking enabled.

variant_id

objectId

ID of the bundle item variant.

variant

Expandable link to the bundle item variant.

quantity_cancelable

int

Quantity of bundle items that are able to be canceled.

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.

delivery

enum

Method of delivery taken automatically from product.delivery.

Possible enum values:

shipmentgiftcardsubscription

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, promotions, or custom logic.

metadata

object

Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API 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.

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.

price_total

currency

Total price added to sub total by multiplying quantity and price.

product_id

objectId

ID of the item product.

product

Expandable link to the item product.

product_name

string

Name of the product.

quantity

int

Quantity of the item being ordered. Defaults to 1.

quantity_canceled

int

Quantity of the item canceled before fulfillment, if applicable.

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.

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.

return_discount_total

currency

Total discount total for returned items.

return_price_total

currency

Total price of returned items.

return_tax_total

currency

Total tax amount of returned items.

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_date_period_start

date

Start date for subscription period.

subscription_paid

boolean

Indicates the item has been fulfilled as a subscription 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.

taxes

array of object

List of tax rules applied to the item based on tax settings or custom logic.

variant_id

objectId

ID of the item variant, if applicable.

variant

Expandable link to the item variant, if applicable.

quantity_cancelable

int

Quantity of items that can be canceled.

quantity_credited

int

Amount of items credited.

quantity_creditable

int

Quantity of items eligible to be used with credit.

quantity_invoiceable

int

Quantity of items eligible to be invoiced.

quantity_invoiced

int

Quantity of invoiced items.

quantity_total

int

Total quantity of items.

quantity_subscription_delivered

int

Quantity of subscriptions delivered.

purchase_option

object

Purchase option selected; standard for one-time purchases or subscription for a subscription plan.

metadata

object

Arbitrary data, typically set in a checkout flow to store custom values. See Frontend API for details.

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

stringauto

Unique incremental order number, assigned automatically using a format configured in general settings.

paid

booleanauto

Indicates the order was paid in full. Always true when payment_marked=true, otherwise depends on the sum of payments.

parent

Order

Expandable link to the parent order.

parent_id

objectId

ID of the parent order.

payment_balance

currencyauto

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.

payments

Payment

Expandable list of payments applied to the order.

pending_invoices

Invoice

Expandable list of invoices that haven't been fully paid.

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.

refunded

booleanauto

Indicates the order was fully refunded. Always true when refund_marked=true, otherwise depends on the sum of refunds.

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

currencyauto

Total tax amount of items returned.

return_item_tax_included

currencyauto

Total tax included amount of items returned, separate from line item values.

return_item_total

currencyauto

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.

shipment_delivery

boolean

Indicates the order has at least one line item with delivery=shipment.

shipment_discount

currency

Shipping discount applied by coupons, promotions, or custom logic.

shipment_price

currencyauto

Total shipping price before discounts.

shipment_rating

objectauto

Object describing the shipping services and rates available for the order. Shipping country must be set before retrieving shipping rates.

shipment_tax

currency

Shipping tax amount, if applicable.

shipment_tax_included

boolean

Indicates shipping total includes taxes, if applicable.

shipment_tax_included_total

currencyauto

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

currencyauto

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.

status

enumauto

Current status of the order. Can be pending, draft, payment_pending, delivery_pending, hold, complete, or canceled.

Possible enum values:

pendingdraftpayment_pendingdelivery_pendingholdcompletecanceled

sub_total

currencyauto

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

booleanrequired

Indicates the order has at least one line item with delivery=subscription.

subscription_id

objectIdauto

ID of the subscription that spawned the order, if applicable.

tax_included_total

currencyauto

Total of taxes applied separately from line items.

tax_total

currencyauto

Total tax amount applied to the order including line items and shipping.

taxes

array of object

List of taxes applied to the order.

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

intauto

Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.

webhook_response

stringauto

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

intauto

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.

The order model

{
  "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. If you wish to generate your own unique ID for the record, it must use BSON ObjectID format for compatibility.

Arguments

account_id

objectIdrequired

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.

billing.account_card_id

objectId

ID of the customer's credit card on file, if applicable.

billing.account_card

account_card

Expandable link to the customer's credit card on file, if applicable.

billing.address1

string

Billing address line 1: street address/PO box/company name.

billing.address2

string

Billing address line 2: apartment/suite/unit/building.

billing.amazon

object

Amazon billing details used when billing.method=amazon.

billing.card

object

Credit card billing details used when billing.method=card.

billing.city

string

Billing city/district/suburb/town/village.

billing.country

string

Two-letter ISO code country code.

billing.first_name

string

Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.

billing.last_name

string

Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.

billing.method

string

Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.

billing.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.

billing.paypal

object

PayPal billing details used when billing.method=paypal.

billing.phone

string

Billing phone number.

billing.state

string

Billing state/county/province/region.

billing.zip

string

Billing zip/postal code.

billing.default

boolean

Indicates billing details represent the customer's default payment method.

billing.intent

object

Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.

billing.affirm

object

Affirm billing details used when billing.method=affirm.

billing.resolve

object

Resolve billing details used when billing.method=resolve.

billing.klarna

object

Klarna billing details used when billing.method=klarna.

billing.ideal

object

Ideal billing details used when billing.method=ideal.

billing.bancontact

object

Bancontact billing details used when billing.method=bancontact.

billing.google

object

Google Pay billing details used when billing.method=google.

billing.apple

object

Apple Pay billing details used when billing.method=apple.

billing.instructions

string

coupon_code

string

Coupon code applied to the order. See coupons 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

objectIdrequired

ID of the bundle item product.

product

Expandable link to the bundle item product.

quantity

int

Quantity of the bundle item being ordered. Defaults to 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

Expandable link to the bundle item product variant.

id

objectIdauto

Unique identifier for the object.

delivery

enum

Method of delivery taken automatically from product.delivery.

Possible enum values:

shipmentgiftcardsubscription

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.

quantity_canceled

int

Quantity of the bundle item canceled before fulfillment, if applicable.

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.

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_cancelable

int

Quantity of bundle items that are able to be canceled.

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.

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 or promotions.

metadata

object

Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API 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.

price

currency

Price of the item. Override this value to set a custom price. Defaults to product price or sale price.

product_id

objectId

ID of the item product.

quantity

int

Quantity of the item being ordered. Defaults to 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.

variant_id

objectId

ID of the item variant, if applicable.

id

objectIdauto

Unique identifier for the item.

delivery

enum

Method of delivery taken automatically from product.delivery.

Possible enum values:

shipmentgiftcardsubscription

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

Expandable link to the item product.

product_name

string

Name of the product.

quantity_canceled

int

Quantity of the item canceled before fulfillment, if applicable.

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.

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.

return_discount_total

currency

Total discount total for returned items.

return_price_total

currency

Total price of returned items.

return_tax_total

currency

Total tax amount of returned items.

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_date_period_start

date

Start date for subscription period.

subscription_paid

boolean

Indicates the item has been fulfilled as a subscription 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

Expandable link to the item variant, if applicable.

quantity_cancelable

int

Quantity of items that can be canceled.

quantity_credited

int

Amount of items credited.

quantity_creditable

int

Quantity of items eligible to be used with credit.

quantity_invoiceable

int

Quantity of items eligible to be invoiced.

quantity_invoiced

int

Quantity of invoiced items.

quantity_total

int

Total quantity of items.

quantity_subscription_delivered

int

Quantity of subscriptions delivered.

purchase_option

object

Purchase option selected; standard for one-time purchases or subscription for a subscription plan.

shipping

object

The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.

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.

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.

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.

hold

boolean

Indicates the order was placed on hold.

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 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, 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.

account

Account

Expandable link to the customer's account.

authorized_payment_id

stringauto

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

objectIdauto

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

dateauto

Period end date applicable when the order was created from a subscription.

date_period_start

dateauto

Period start date applicable when the order was created from a subscription.

date_webhook_first_failed

dateauto

Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record.

delivered

booleanauto

Indicates the order was completely fulfilled. Always true when delivery_marked=true, otherwise depends on the sum of shipments, giftcards, and subscriptions.

discount_total

currencyauto

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

currencyauto

Grand total including items, shipping and taxes.

invoices

Invoice

Expandable link to the invoice the payment was applied to, if applicable.

item_discount

currencyauto

Total discount applied to line items.

item_quantity

intauto

Total quantity of all line items.

item_quantity_cancelable

int

Total quantity of cancelable items on the order.

item_quantity_canceled

intauto

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

intauto

Total quantity of line items that can be fulfilled.

item_quantity_delivered

intauto

Total quantity of line items that have been fulfilled.

item_quantity_giftcard_deliverable

intauto

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

intauto

Total quantity of line items that can still be returned.

item_quantity_returned

intauto

Total quantity of line items that have been returned.

item_quantity_shipment_deliverable

intauto

Total quantity of line items that can be fulfilled by shipment. Applies when item.delivery=shipment.

item_quantity_subscription_deliverable

intauto

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

currencyauto

Total taxes applied to line items.

notifications

Notification

Expandable list of notifications sent on behalf of the order.

number

stringauto

Unique incremental order number, assigned automatically using a format configured in general settings.

paid

booleanauto

Indicates the order was paid in full. Always true when payment_marked=true, otherwise depends on the sum of payments.

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

currencyauto

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.

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.

refunded

booleanauto

Indicates the order was fully refunded. Always true when refund_marked=true, otherwise depends on the sum of refunds.

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

currencyauto

Total tax amount of items returned.

return_item_tax_included

currencyauto

Total tax included amount of items returned, separate from line item values.

return_item_total

currencyauto

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

currencyauto

Total shipping price before discounts.

shipment_rating

objectauto

Object describing the shipping services and rates available for the order. Shipping country must be set before retrieving shipping rates.

shipment_tax_included_total

currencyauto

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

currencyauto

Total shipping price after discounts.

shipments

Shipment

Expandable list of shipments created from the order.

status

enumauto

Current status of the order. Can be pending, draft, payment_pending, delivery_pending, hold, complete, or canceled.

Possible enum values:

pendingdraftpayment_pendingdelivery_pendingholdcompletecanceled

sub_total

currencyauto

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

objectIdauto

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

currencyauto

Total of taxes applied separately from line items.

tax_total

currencyauto

Total tax amount applied to the order including line items and shipping.

webhook_attempts_failed

intauto

Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.

webhook_response

stringauto

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

intauto

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 for details.

test

boolean

Indicates the order was made in test mode.

closed

boolean

Indicates the order is closed.

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.

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.

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.

POST/orders

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.post('/orders', {
  account_id: '5a9ea7ba3f95740a914267f1',
  items: [
    {
      product_id: '5cad15bc9b14d1990724663a',
      quantity: 2,
    }
  ],
  billing: {
    ...
  },
  shipping: {
    ...
  },
  coupon_code: 'FREESHIPPING',
});

Response

{
  "id": "5cad15bc9b14d1990724663a",
  "account_id": "5a9ea7ba3f95740a914267f1",
  "billing": {...},
  "shipping": {...},
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "delivered": false,
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "paid": false,
  "payment_balance": -18.98,
  "payment_total": 0,
  "refund_total": 0,
  "refunded": false,
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "payment_pending",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

Retrieve an order

Retrieve an existing order using the ID that was returned when created.

Arguments

id

objectIdrequired

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 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 for more details.

GET/orders/:id

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/orders/{id}', {
  id: '5cad15bc9b14d1990724663a',
});

Response

{
  "id": "5cad15bc9b14d1990724663a",
  "account_id": "5a9ea7ba3f95740a914267f1",
  "billing": {...},
  "shipping": {...},
  "items": [
    {
      "id": "5a9ea7ba3f95740a914267f2",
      "product_id": "5cad15bc9b14d1990724663b",
      "quantity": 2,
      "price": 9.99,
      "price_total": 18.98,
      "shipment_weight": 1.5,
      ...
    }
  ],
  "coupon_code": "FREESHIPPING",
  "currency": "USD",
  "date_created": "2019-04-01T00:00:00.000Z",
  "delivered": false,
  "discount_total": 0,
  "grand_total": 18.98,
  "item_quantity": 2,
  "item_shipment_weight": 3.0,
  "item_tax": 0,
  "number": "100101",
  "paid": false,
  "payment_balance": -18.98,
  "payment_total": 0,
  "refund_total": 0,
  "refunded": false,
  "shipment_price": 0,
  "shipment_total": 0,
  "status": "payment_pending",
  "sub_total": 0,
  "tax_total": 0,
  ...
}

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

account_id

objectIdrequired

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.

billing.account_card_id

objectId

ID of the customer's credit card on file, if applicable.

billing.account_card

account_card

Expandable link to the customer's credit card on file, if applicable.

billing.address1

string

Billing address line 1: street address/PO box/company name.

billing.address2

string

Billing address line 2: apartment/suite/unit/building.

billing.amazon

object

Amazon billing details used when billing.method=amazon.

billing.card

object

Credit card billing details used when billing.method=card.

billing.city

string

Billing city/district/suburb/town/village.

billing.country

string

Two-letter ISO code country code.

billing.first_name

string

Billing first name. If name is updated, then first_name will be automatically updated as the first word of the name.

billing.last_name

string

Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.

billing.method

string

Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.

billing.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.

billing.paypal

object

PayPal billing details used when billing.method=paypal.

billing.phone

string

Billing phone number.

billing.state

string

Billing state/county/province/region.

billing.zip

string

Billing zip/postal code.

billing.default

boolean

Indicates billing details represent the customer's default payment method.

billing.intent

object

Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.

billing.affirm

object

Affirm billing details used when billing.method=affirm.

billing.resolve

object

Resolve billing details used when billing.method=resolve.

billing.klarna

object

Klarna billing details used when billing.method=klarna.

billing.ideal

object

Ideal billing details used when billing.method=ideal.

billing.bancontact

object

Bancontact billing details used when billing.method=bancontact.

billing.google

object

Google Pay billing details used when billing.method=google.

billing.apple

object

Apple Pay billing details used when billing.method=apple.

billing.instructions

string

coupon_code

string

Coupon code applied to the order. See coupons 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

objectIdrequired

ID of the bundle item product.

product

Expandable link to the bundle item product.

quantity

int

Quantity of the bundle item being ordered. Defaults to 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

Expandable link to the bundle item product variant.

id

objectIdauto

Unique identifier for the object.

delivery

enum

Method of delivery taken automatically from product.delivery.

Possible enum values:

shipmentgiftcardsubscription

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.

quantity_canceled

int

Quantity of the bundle item canceled before fulfillment, if applicable.

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.

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_cancelable

int

Quantity of bundle items that are able to be canceled.

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.

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 or promotions.

metadata

object

Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API 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.

price

currency

Price of the item. Override this value to set a custom price. Defaults to product price or sale price.

product_id

objectId

ID of the item product.

quantity

int

Quantity of the item being ordered. Defaults to 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.

variant_id

objectId

ID of the item variant, if applicable.

id

objectIdauto

Unique identifier for the item.

delivery

enum

Method of delivery taken automatically from product.delivery.

Possible enum values:

shipmentgiftcardsubscription

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

Expandable link to the item product.

product_name

string

Name of the product.

quantity_canceled

int

Quantity of the item canceled before fulfillment, if applicable.

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.

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.

return_discount_total

currency

Total discount total for returned items.

return_price_total

currency

Total price of returned items.

return_tax_total

currency

Total tax amount of returned items.

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_date_period_start

date

Start date for subscription period.

subscription_paid

boolean

Indicates the item has been fulfilled as a subscription 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

Expandable link to the item variant, if applicable.

quantity_cancelable

int

Quantity of items that can be canceled.

quantity_credited

int

Amount of items credited.

quantity_creditable

int

Quantity of items eligible to be used with credit.

quantity_invoiceable

int

Quantity of items eligible to be invoiced.

quantity_invoiced

int

Quantity of invoiced items.

quantity_total

int

Total quantity of items.

quantity_subscription_delivered

int

Quantity of subscriptions delivered.

purchase_option

object

Purchase option selected; standard for one-time purchases or subscription for a subscription plan.

shipping

object

The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.

id

objectIdrequired

Unique identifier for the order.

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

stringauto

The id of an authorized payment. When "Require payment authorization" is enabled in payment settings, the order will be rejected if initial payment fails.

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

objectIdauto

ID of the cart that converted to this order, if applicable.

closed

boolean

Indicates the order is closed.

comments

string

Customer notes provided when placing the order, if any.

coupon

Coupon

Expandable link to the coupon 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.

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

dateauto

Period end date applicable when the order was created from a subscription.

date_period_start

dateauto

Period start date applicable when the order was created from a subscription.

date_scheduled

date

Scheduled date for the order.

date_webhook_first_failed

dateauto

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

booleanauto

Indicates the order was completely fulfilled. Always true when delivery_marked=true, otherwise depends on the sum of shipments, giftcards, and subscriptions.

delivery_marked

boolean

Indicates the order was marked as fulfilled, manually or automatically.

discount_total

currencyauto

Total discount amount.

discounts

array of object

List of discounts applied to the order.

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 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.

grand_total

currencyauto

Grand total including items, shipping and taxes.

guest

boolean

Indicates the customer was not logged in when placing the order.

hold

boolean

Indicates the order was placed on hold.

invoices

Invoice

Expandable link to the invoice the payment was applied to, if applicable.

item_discount

currencyauto

Total discount applied to line items.

item_quantity

intauto

Total quantity of all line items.

item_quantity_cancelable

int

Total quantity of cancelable items on the order.

item_quantity_canceled

intauto

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

intauto

Total quantity of line items that can be fulfilled.

item_quantity_delivered

intauto

Total quantity of line items that have been fulfilled.

item_quantity_giftcard_deliverable

intauto

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

intauto

Total quantity of line items that can still be returned.

item_quantity_returned

intauto

Total quantity of line items that have been returned.

item_quantity_shipment_deliverable

intauto

Total quantity of line items that can be fulfilled by shipment. Applies when item.delivery=shipment.

item_quantity_subscription_deliverable

intauto

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

currencyauto

Total taxes applied to line items.

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 for details.

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

stringauto

Unique incremental order number, assigned automatically using a format configured in general settings.

paid

booleanauto

Indicates the order was paid in full. Always true when payment_marked=true, otherwise depends on the sum of payments.

parent

Order

Expandable link to the parent order.

parent_id

objectId

ID of the parent order.

payment_balance

currencyauto

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.

payments

Payment

Expandable list of payments applied to the order.

pending_invoices

Invoice

Expandable list of invoices that haven't been fully paid.

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.

refunded

booleanauto

Indicates the order was fully refunded. Always true when refund_marked=true, otherwise depends on the sum of refunds.

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

currencyauto

Total tax amount of items returned.

return_item_tax_included

currencyauto

Total tax included amount of items returned, separate from line item values.

return_item_total

currencyauto

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, promotions, or custom logic.

shipment_price

currencyauto

Total shipping price before discounts.

shipment_rating

objectauto

Object describing the shipping services and rates available for the order. Shipping country must be set before retrieving shipping rates.

shipment_tax

currency

Shipping tax amount, if applicable.

shipment_tax_included

boolean

Indicates shipping total includes taxes, if applicable.

shipment_tax_included_total

currencyauto

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

currencyauto

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.

status

enumauto

Current status of the order. Can be pending, draft, payment_pending, delivery_pending, hold, complete, or canceled.

Possible enum values:

pendingdraftpayment_pendingdelivery_pendingholdcompletecanceled

sub_total

currencyauto

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

objectIdauto

ID of the subscription that spawned the order, if applicable.

tax_included_total

currencyauto

Total of taxes applied separately from line items.

tax_total

currencyauto

Total tax amount applied to the order including line items and shipping.

taxes

array of object

List of taxes applied to the order.

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

intauto

Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.

webhook_response

stringauto

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

intauto

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.

PUT/orders/:id

const swell = require('swell-node').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',
  },
});

Response

{
  "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 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 for more details.

limit

int

Limit the number of records returned, ranging between 1 and 1000. Defaults to 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 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 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 for more details.

GET/orders

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.get('/orders', {
  where: {
    account_id: '592ef41c57ce232e1ce3729e',
  },
  limit: 25,
  page: 1,
});

Response

{
  "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,
  "pages": {
    "1": {
      "start": 1,
      "end": 25
    },
    "2": {
      "start": 26,
      "end": 50
    },
    "2": {
      "start": 51,
      "end": 51
    }
  }
}

Delete an order

Delete an order permanently.

Arguments

id

objectIdrequired

The id of the order to delete.

DELETE/orders/:id

const swell = require('swell-node').init('store-id', 'secret-key');

await swell.delete('/orders/{id}', {
  id: '5cad15bc9b14d1990724663a',
});

Response

{
  "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,
  ...
}

← Back: Carts Next: Payments →

Orders

The order model

Fields

id

account_id

account

account_credit_amount

account_credit_applied

account_info_saved

account_logged_in

authorized_payment

authorized_payment_id

billing

billing.name

billing.first_name

billing.last_name

billing.address1

billing.address2

billing.city

billing.state

billing.zip

billing.country

billing.phone

billing.method

billing.card

card.token

card.exp_month

card.exp_year

card.brand

card.last4

card.gateway

card.test

card.address_check

card.zip_check

card.cvc_check

billing.default

billing.account_card_id

billing.account_card

billing.amazon

amazon.access_token

amazon.order_reference_id

amazon.checkout_session_id

billing.paypal

paypal.payer_id

paypal.payment_id

paypal.nonce

paypal.authorization_id

paypal.order_id

billing.intent

billing.affirm

affirm.checkout_token

billing.resolve

resolve.charge_id

billing.klarna

klarna.source

billing.ideal

ideal.token

billing.bancontact

bancontact.source

billing.google

google.nonce

google.gateway

billing.apple

apple.nonce

apple.gateway

billing.instructions

cancel_reason

canceled

cart

cart_id

closed

comments

coupon

coupon_code

coupon_id

credit_total

credits

currency

currency_rate

date_canceled