Backend API

Fields
idobjectId

Unique identifier for the order.

account_idobjectIdrequired

The id of the customer's account. During checkout, customer accounts without a password are designated as guest=true.

accountAccount

Expandable link to the customer's account.

account_credit_amountcurrency

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

account_credit_appliedboolean

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

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_paymentPayment

Expandable link to an authorized payment.

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.

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.

cartCart

Expandable link to the cart.

cart_idobjectIdauto

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

closedboolean

Indicates the order is closed.

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.

credit_totalcurrency

Total amount of additional credit applied to the order.

creditsCredit memo

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

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.

locationstring

Location to purchase products from, when using multi-location inventory.

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_scheduleddate

Scheduled date for the order.

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.

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.

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.

giftboolean

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

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.

grand_totalcurrencyauto

Grand total including items, shipping and taxes.

trial_grand_totalcurrency

Grand total of items with a trial period, charged when their trials end.

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.

item_discountcurrencyauto

Total discount applied to line items.

trial_item_discountcurrency

Total discount applied to items with a trial period.

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.

trial_item_taxcurrency

Total tax applied to items with a trial period.

item_tax_includedboolean

Indicates line item prices include taxes.

itemsarray of object

List of line items describing the products ordered.

metadataobject

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

nextOrder

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

next_idobjectId

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

notesstring

Internal admin notes, not visible to the customer. This field holds a single block of text. To record a series of notes against the order, each attributed to a user, see Notes.

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.

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.

paymentsPayment

Expandable list of payments applied to the order.

pending_invoicesInvoice

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

prevOrder

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

prev_idobjectId

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

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.

scheduleobject

Scheduling for recurring orders.

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.

shipment_total_creditedcurrency

Total shipping price for items credited on the order.

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.

Possible enum values:

pendingdraftpayment_pendingdelivery_pendingholdcompletecanceled
sub_totalcurrencyauto

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

trial_sub_totalcurrency

Subtotal of items with a trial period, charged when their trials end.

subscriptionSubscription

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

subscription_deliveryboolean

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

subscription_idobjectIdauto

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

tax_included_totalcurrencyauto

Total of taxes applied separately from line items.

trial_tax_included_totalcurrency

Total of items with a trial period including taxes, if applicable.

tax_totalcurrencyauto

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

taxesarray of object

List of taxes applied to the order.

taxes_fixedboolean

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

testboolean

Indicates the order was made in test mode.

trialboolean

Indicates the order contains at least one item with a trial period.

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.

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