Backend API

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.

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.

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.

metadata

object

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

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.

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.

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

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.

shipping

object

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

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

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.

shipping

object

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

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

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