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

idobjectId

Unique identifier for the order.

account_idobjectIdrequired

The id of the customer's account.

accountAccount

Expandable link to the customer's account.

account_credit_amountcurrency

Amount of customer's account credit applied for initial payment, if applicable.

account_info_savedboolean

Indicates the customer chose to save shipping and billing information to their account when submitting the order.

account_logged_inboolean

Indicates the customer was logged into their account when placing the order.

authorized_payment_idstringauto

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_paymentPayment

Expandable link to an authorized payment.

billingobject

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

cancel_reasonstring

A message describing the reason for cancelling the order, if applicable.

canceledboolean

Indicates the order was completely canceled.

cart_idobjectIdauto

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

cartCart

Expandable link to the cart.

commentsstring

Customer notes provided when placing the order, if any.

couponCoupon

Expandable link to the coupon applied to the order.

coupon_codestring

Coupon code applied to the order.

coupon_idobjectId

ID of the coupon applied to the order.

creditsCredit Memo

Expandable list of account credit transactions. Balance of these transactions is kept in balance.

credit_totalcurrency

Total amount of additional credit applied to the order.

currencystring

Three-letter ISO currency code in uppercase. Defaults to the store's base currency.

currency_ratefloat

Currency percentage used in calculating the fixed amount.

date_canceleddate

Date the order was canceled, if applicable.

date_createddateauto

Date and time the order was created.

date_payment_retrydate

When automated payment has failed, this is the date when the system will automatically retry.

date_period_enddateauto

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

date_period_startdateauto

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

date_updateddateauto

Date and time the order was last updated.

date_webhook_first_faileddateauto

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

deliveredbooleanauto

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

delivery_markedboolean

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

discount_totalcurrencyauto

Total discount amount.

discountsarray of object

List of discounts applied to the order.

display_currencystring

Three-letter ISO currency code representing the user's preferred display currency, if applicable.

display_localestring

Locale code representing the user's preferred display locale, if applicable.

gift_messagestring

Optional message to include with the order when shipping to the recipient.

giftcard_deliveryboolean

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

giftcard_totalcurrency

Total payment amount applied to the order from giftcards.

giftcardsarray of object

List of gift cards applied to the order.

giftboolean

Indicates the order is intended as a gift for the recipient.

grand_totalcurrencyauto

Grand total including items, shipping and taxes.

guestboolean

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

holdboolean

Indicates the order was placed on hold.

invoicesInvoice

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

itemsarray of object

List of line items describing the products ordered.

item_discountcurrencyauto

Total discount applied to line items.

item_quantityintauto

Total quantity of all line items.

item_quantity_cancelableint

Total quantity of cancelable items on the order.

item_quantity_canceledintauto

Total quantity of line items canceled.

item_quantity_creditableint

Total quantity of line items that can be credited.

item_quantity_creditedint

Total quantity of items credited on the order.

item_quantity_deliverableintauto

Total quantity of line items that can be fulfilled.

item_quantity_deliveredintauto

Total quantity of line items that have been fulfilled.

item_quantity_giftcard_deliverableintauto

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

item_quantity_invoiceableint

Total quantity of items eligible for invoicing on the order.

item_quantity_invoicedint

Total quantity of items invoiced on the order.

item_quantity_returnableintauto

Total quantity of line items that can still be returned.

item_quantity_returnedintauto

Total quantity of line items that have been returned.

item_quantity_shipment_deliverableintauto

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

item_quantity_subscription_deliverableintauto

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

item_shipment_weightfloat

Total shipping weight of all line items.

item_taxcurrencyauto

Total taxes applied to line items.

item_tax_includedboolean

Indicates line item prices include taxes.

metadataobject

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

notesstring

Internal admin notes, not visible to the customer.

notificationsNotification

Expandable list of notifications sent on behalf of the order.

numberstringauto

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

paidbooleanauto

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

parentOrder

Expandable link to the parent order.

parent_idobjectId

ID of the parent order.

paymentsPayment

Expandable list of payments applied to the order.

payment_balancecurrencyauto

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_errorstring

A message describing the last payment error, if one occurred.

payment_markedboolean

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

payment_retry_countint

The number of times automatic payment has been attempted.

payment_retry_resolvestring

The method used to resolve automatic payment when all retry attempts are exhausted. Can be blank (do nothing), canceled, or unpaid.

payment_totalcurrency

Sum of payments applied to the order, not including refunds.

pending_invoicesInvoice

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

promotion_idsarray of child_scalar

List of promotion IDs applied to the order.

promotionsPromotion

Expandable list of promotions applied to the order.

refund_markedboolean

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

refund_totalcurrency

Sum of refunds on payments applied to the order.

refundedbooleanauto

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

refundsRefund

Expandable list of refunds applied to the order.

return_credit_taxcurrency

Total additional credit tax applied to the order from returns, if applicable

return_credit_totalcurrency

Total additional credit amount applied to the order from returns.

return_item_taxcurrencyauto

Total tax amount of items returned.

return_item_tax_includedcurrencyauto

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

return_item_totalcurrencyauto

Total amount of items returned, minus discounts.

return_totalcurrency

Grand total amount applied to the order from returns.

shipment_deliveryboolean

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

shipment_discountcurrency

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

shipment_pricecurrencyauto

Total shipping price before discounts.

shipment_ratingobjectauto

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

shipment_taxcurrency

Shipping tax amount, if applicable.

shipment_tax_includedboolean

Indicates shipping total includes taxes, if applicable.

shipment_tax_included_totalcurrencyauto

Total shipping price including taxes and discount. Allows for an alternate display style as normally shipment_total and tax_total are shown separately.

shipment_totalcurrencyauto

Total shipping price after discounts.

shipmentsShipment

Expandable list of shipments created from the order.

shippingobject

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

statusenumauto

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

sub_totalcurrencyauto

Sum of all line items before discounts, taxes and shipping.

subscription_deliverybooleanrequired

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

subscription_idobjectIdauto

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

subscriptionSubscription

Expandable link to the subscription that spawned the order, if applicable.

tax_included_totalcurrencyauto

Total of taxes applied separately from line items.

tax_totalcurrencyauto

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

taxesarray of object

List of taxes applied to the order.

webhook_attempts_failedintauto

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

webhook_responsestringauto

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_statusintauto

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_fixedboolean

Indicates the order is tax-exempt. Taxes will not be calculated or applied when true.

draftboolean

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.

testboolean

Indicates the order was made in test mode.

shipment_total_creditedcurrency

Total shipping price for items credited on the order.

prev_idobjectId

This never gets set by Swell. A customer must explicitly set this field to a particular order ID.

prevOrder

If prev_id is set by the customer, prev will link to the order with the given prev_id.

next_idobjectId

This never gets set by Swell. A customer must explicitly set this field to a particular order ID.

nextOrder

If next_id is set by the customer, next will link to the order with the given next_id.

account_credit_appliedboolean

Indicates the customer’s account credit is applied when submitting the order.

date_webhook_last_succeededdate

Date the order webhook last succeeded, if applicable. Value is unset after an order webhook fails to return for the record.

trial_price_totalcurrency

Total of all trial prices on the order.

trial_discount_totalcurrency

Total of all trial discounts on the order.

trial_tax_totalcurrency

Total of all tax for trial items on the order.

trial_sub_totalcurrency

The subtotal of all trial items on the order.

trial_item_discountcurrency

The discount for trial items on the order.

trial_item_taxstring

The tax of trial items on the order.

trial_tax_included_totalcurrency

The total of trial item tax added to the order's trial_grand_total.

trial_grand_totalcurrency

The grand total for trial items on an order.

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.

Arguments

account_idobjectIdrequired

ID of the customer's account.

billingobject

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

coupon_codestring

Coupon code applied to the order. See coupons for details.

itemsarray of object

List of line items describing the products ordered.

shippingobject

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

idobjectIdrequired

The id of the order to retrieve.

expandstring

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.

fieldsstring

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.

includestring

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_idobjectIdrequired

ID of the customer's account.

billingobject

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

coupon_codestring

Coupon code applied to the order. See coupons for details.

itemsarray of object

List of line items describing the products ordered.

shippingobject

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

expandstring

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.

fieldsstring

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

Include one or more arbitrary queries in the response which are potentially related to the main query.

See including for more details.

limitint

Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.

pageint

The page number of results to return given the specified or default limit.

searchstring

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.

sortstring

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.

whereobject

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

idobjectIdrequired

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