Filter
What would you like to search for?
Guides
Swell has a complete Order Management System (OMS) with integrated models for carts, orders, payments, refunds, shipments, and returns. Together, these provide a customizable workflow for creating, managing, and fulfilling orders—with the ability to handle returns and abandoned carts out of the box.
Most shopping flows use a cart to keep track of the items the customer wants to buy. The cart contains the shipping and billing information as well. Think of a cart as a staging area for an order. It contains all the information needed to complete a checkout flow.
Swell's abandoned cart feature sends notifications to a customer who has left items in their cart. By default, this action is engaged once a cart has been inactive for at least three hours. For an abandoned cart, the abandoned field will be marked true until the cart sees additional activity.
Enable abandoned cart notifications by navigating to Settings > Notifications > Abandoned cart in the Swell dashboard. Here you can set a variety of parameters such as when a cart is considered abandoned, follow-up notification sequencing, and the contents of those messages.
A checkout flow is a self-serve mechanism for customers to provide delivery and payment details. This process converts their cart into an order that is ready to be fulfilled. When checkout succeeds, all items from the cart are duplicated to an order, and the cart status becomes converted.
Swell provides a hosted checkout which is available on any cart via the checkout_url field. You can also build your own custom checkout flows using our APIs.
Every checkout has an account assigned to it by email, but not every checkout requires a login with password credentials. By default, Swell's hosted checkout allows for guests to make purchases. These customers will be recorded with an email and shipping information only and guest purchases can be identified by guest=true.
Orders can be created from customer carts via a checkout flow, directly via the Backend API, or manually from the dashboard. You can check whether an order originated from a cart using the cart or cart_id fields.
When an order is created, the order number is automatically assigned. The number format is customizable from the dashboard under General > Settings > Order number format.
In the case of one-time purchases, a single order will handle the entire purchase flow. When an order contains subscription products, a subscription entry will be generated to handle recurring billing and fulfillment. Each subscription references the order that generated it as order_id.
For subscriptions with physical products, each interval generates a new order to be fulfilled and charges the customer's saved payment method. These recurring orders can be traced back to the subscription that generated them using the subscription_id or subscription fields.
Subscriptions containing only virtual products do not generate new orders since there are no items to be fulfilled. On each billing interval, an invoice is generated for charging the customer's saved payment method. Like recurring orders, invoices reference the associated subscription with the subscription_id and subscription fields.
Swell features real-time webhooks that allow you to set fields on the order object before being submitted. Use these to update tax and shipping rates or make other determinations such as fraud risk and regulatory approval before processing an order.
The status of an order is provisioned by the system once certain parameters have been met. It is set to "pending" by default. As an order progresses through its lifecycle, the system updates the status accordingly. This is reflected in both the dashboard and via API. An order lifecycle generally includes "pending", "payment_pending", "delivery_pending", and "complete".
- status="pending": The default status of an order.
- status="draft": The status for an order that has been created but not submitted; draft orders are carts where draft=true which will flag the order in the UI.
- status="payment_pending": denotes an order that has not yet been paid in full
- status="delivery_pending": one or more items in the order are awaiting delivery
- status="complete": all items have been received by the customer
- status="hold": the order has been put on hold
- status="canceled": the order was canceled
Payments and refunds are always related to an order or invoice, and any transaction will automatically update the relevant fields. Orders and invoices will have paid=true when payment_balance is zero or payment_marked=true is manually set. Refunds are issued against a payment and cannot exceed the total payment amount.
Relevant fields
- authorized_payment_id
- authorized_payment
- paid
- payment_balance
- payment_marked
- payment_total
- payments
- refund_marked
- refund_total
- refunded
During checkout, the payment gateways you have configured will determine how customers can pay for their orders. By default, they can also redeem a gift card or use account credit. Alternative payment methods like cash or bank transfers can be defined in Settings > Payments.
When creating an order from the dashboard, an invoice notification can be sent to the customer with a link to pay for their order. This is the same checkout_url that is present on carts.
At the time of checkout, a user will select a shipment service, which includes both a carrier (e.g., UPS) and a shipping method (e.g., 2-day delivery). This combination of a carrier and shipping method calculates the shipment_total based on the customer's shipping information. Swell calculates shipping rates at the product level based on variables such as the product dimensions(shipment_dimensions), weight(shipment_weight), and quantity per package(shipment_package_quantity).
Shipping rules are defined within Swell Admin under Settings > Shipping. This is where you set your store's store location which is used to calculate shipping rates. Shipping rules created in the Shipping tab can be applied to orders via checkout by the customer. These rules are highly flexible and can be overridden when designated parameters are met. Swell also allows local pick-up options.
Dynamic real-time shipping rate calculations can also be implemented through integrations with shipping carriers and Swell's webhook support. These rates will be calculated during checkout based on the product information within the customer's cart.
Swell can be used to sell virtual products such as services, memberships, and digital goods. Because of the many potential use cases, there isn't a standard delivery mechanism for these; however, you can use queued webhooks and our Backend API to fulfill virtual products in a way that suits your needs.
For more details regarding shipping setup and fulfillment, see our dedicated guide.
Fields
Unique identifier for the order.
The id of the customer's account.
Expandable link to the customer's account.
Amount of customer's account credit applied for initial payment, if applicable.
Indicates the customer chose to save shipping and billing information to their account when submitting the order.
Indicates the customer was logged into their account when placing the order.
The id of an authorized payment. When "Require payment authorization" is enabled in payment settings, the order will be rejected if initial payment fails.
Expandable link to an authorized payment.
The customer's billing details. Defaults to account.billing. Updating billing will also update the corresponding account billing object.
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. If name is updated, then first_name will be automatically updated as the first word of the name.
Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Billing city/district/suburb/town/village.
Billing state/county/province/region.
Billing zip/postal code.
Two-letter ISO country code.
Billing phone number.
Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.
Credit card billing details used when billing.method=card.
Token generated by Swell Checkout or Stripe.js.
Two-digit number representing the credit card expiration month.
Four-digit number representing the credit card expiration year.
Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Last four digits of the card number.
ID of the payment gateway that should be used to process payments.
Indicates this is a test card.
When used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable, or unchecked.
Indicates billing details represent the customer's default payment method.
ID of the customer's credit card on file, if applicable.
Expandable link to the customer's credit card on file, if applicable.
Amazon billing details used when billing.method=amazon.
Amazon access token provided when a customer authorizes payment in a storefront.
Amazon order reference ID created when a customer initiates payment in a storefront.
PayPal billing details used when billing.method=paypal.
PayPal payer ID provided when a customer authorizes payment in a storefront.
PayPal payment ID created when a customer initiates payment in a storefront.
One-time use reference element used to communicate payment information to a payment gateway.
PayPal authorization ID when a customer makes a payment using their PayPal account.
Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.
Affirm billing details used when billing.method=affirm.
Token used to communicate payment information to the gateway.
Resolve billing details used when billing.method=resolve.
Charge ID returned by the payment gateway for the payment.
Klarna billing details used when billing.method=klarna.
Payment information returned by the gateway during payment initialization.
Ideal billing details used when billing.method=ideal.
Token used to communicate payment information to the gateway.
Bancontact billing details used when billing.method=bancontact.
Payment information returned by the gateway during payment initialization.
Google Pay billing details used when billing.method=google.
One-time use reference element used to communicate payment information to a payment gateway.
Gateway used to facilitate the transaction. For example, gateway=braintree.
Apple Pay billing details used when billing.method=apple.
One-time use reference element used to communicate payment information to a payment gateway.
Gateway used to facilitate the transaction. For example, gateway=braintree.
A message describing the reason for cancelling the order, if applicable.
Indicates the order was completely canceled.
ID of the cart that converted to this order, if applicable.
Expandable link to the cart.
Customer notes provided when placing the order, if any.
Expandable link to the coupon applied to the order.
Coupon code applied to the order.
ID of the coupon applied to the order.
Expandable list of account credit transactions. Balance of these transactions is kept in balance.
Total amount of additional credit applied to the order.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Currency percentage used in calculating the fixed amount.
Date the order was canceled, if applicable.
Date and time the order was created.
When automated payment has failed, this is the date when the system will automatically retry.
Period end date applicable when the order was created from a subscription.
Period start date applicable when the order was created from a subscription.
Date and time the order was last updated.
Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record.
Indicates the order was completely fulfilled. Always true when delivery_marked=true, otherwise depends on the sum of shipments, giftcards, and subscriptions.
Indicates the order was marked as fulfilled, manually or automatically.
Total discount amount.
List of discounts applied to the order.
Unique identifier for the object.
Fixed discount amount.
Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.
Object describing the discount rule details. Custom discounts don't require this value.
Three-letter ISO currency code representing the user's preferred display currency, if applicable.
Locale code representing the user's preferred display locale, if applicable.
Optional message to include with the order when shipping to the recipient.
Indicates the order has at least one line item with delivery=giftcard.
Total payment amount applied to the order from giftcards.
List of gift cards applied to the order.
Unique identifier for the object.
Amount of the gift card balance to spend for initial payment. If not specified, each gift cards will be spent in order until payment is completed.`
Gift card code to apply. A validation error will be returned if the code is not valid.
Fully formatted gift card code for display purposes.
Last four digits of the gift card code.
Expandable link to the gift card record.
Indicates the order is intended as a gift for the recipient.
Grand total including items, shipping and taxes.
Indicates the customer was not logged in when placing the order.
Indicates the order was placed on hold.
Expandable link to the invoice the payment was applied to, if applicable.
List of line items describing the products ordered.
Unique identifier for the item.
List of items offered as a bundle. Defaults to product.bundle_items.
Unique identifier for the object.
ID of the bundle item product.
Method of delivery taken automatically from product.delivery.
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.
Unique identifier for the object.
Name of the product option. Populated automatically when adding an option by ID.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Indicates the option refers to a subscription plan interval.
Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.
Indicates the option refers to a variant aspect.
Expandable link to the bundle item product.
Quantity of the bundle item being ordered. Defaults to 1.
Quantity of the bundle item canceled before fulfillment, if applicable.
Quantity of stock consumed by the bundle item, if applicable.
Quantity of the bundle item that can be fulfilled, if applicable.
Quantity of the bundle item that has been fulfilled, if applicable.
Quantity of the bundle item that can be fulfilled by a gift card. Applies when delivery=giftcard.
Quantity of the bundle item that has been restocked after a return, if applicable.
Quantity of the bundle item that can still be returned after fulfillment, if applicable.
Total quantity of bundle items that have been returned.
Quantity of the bundle item that can be fulfilled by a shipment. Applies when delivery=shipment.
Quantity of the bundle item that can be fulfilled by a subscription. Applies when delivery=subscription.
Total quantity of the bundle item to be fulfilled, calculated as item.quantity * bundle_item.quantity.
Shipping weight taken automatically from product.shipment_weight, if applicable.
Indicates whether the bundle item has stock tracking enabled.
ID of the bundle item variant.
Expandable link to the bundle item variant.
Quantity of bundle items that are able to be canceled.
Quantity of shipments that have been delivered.
Method of delivery taken automatically from product.delivery.
Description used for custom line items, when product is not defined.
Total discount amount divided by quantity.
Total discount applied to the item.
List of discounts applied to the item by coupons, promotions, or custom logic.
Unique identifier for the object. Refers to one of the IDs in the order discounts object.
Fixed discount amount.
Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API for details.
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.
Unique identifier for the object.
Name of the product option. Populated automatically when adding an option by ID.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Indicates the option refers to a subscription plan interval.
Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.
Indicates the option refers to a variant aspect.
Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed.
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.
Total price added to sub total by multiplying quantity and price.
Expandable link to the item product.
ID of the item product.
Quantity of the item being ordered. Defaults to 1.
Quantity of the item canceled before fulfillment, if applicable.
Quantity of stock consumed by the item, if applicable.
Quantity of the item that can be fulfilled, if applicable.
Quantity of the item that has been fulfilled, if applicable.
Quantity of the item that can be fulfilled by a gift card. Applies when delivery=giftcard.
Quantity of the item that has been restocked after a return, if applicable.
Quantity of the item that can still be returned after fulfillment, if applicable.
Quantity of the item that has been returned after fulfillment, if applicable.
Quantity of the item that can be fulfilled by a shipment. Applies when delivery=shipment.
Quantity of the item that can be fulfilled by a subscription. Applies when delivery=subscription.
Shipping weight taken automatically from product.shipment_weight, if applicable.
Indicates whether the item has stock tracking enabled.
Refers to the subscription interval that applies when delivery=subscription.
Refers to the subscription interval count that applies when delivery=subscription.
Indicates the item has been fulfilled as a subscription and marked as paid by reference to this order.
Refers to the subscription trial period that applies when delivery=subscription.
Total tax amount divided by quantity.
Total tax applied to the item.
List of tax rules applied to the item based on tax settings or custom logic.
Unique identifier for the object. Refers to one of the IDs in the order taxes object.
Fixed tax amount.
ID of the item variant, if applicable.
Expandable link to the item variant, if applicable.
Start date for subscription period.
Quantity of items that can be canceled.
Amount of items credited.
Quantity of items eligible to be used with credit.
Quantity of items eligible to be invoiced.
Quantity of invoiced items.
Total discount total for returned items.
Total price of returned items.
Total tax amount of returned items.
Total quantity of items.
Quantity of subscriptions delivered.
Purchase option selected; standard for one-time purchases or subscription for a subscription plan.
Designates the type of purchase option: standard for one-time purchases, subscription for a subscription plan.
ID of the purchase option.
The name of the purchase option.
Price of the purchase option.
ID of the subscription plan, if applicable.
Name of the subscription plan, if applicable.
Billing schedule for the subscription plan, if applicable.
Billing interval for the subscription plan. Can be monthly, weekly, daily, or yearly.
Multiplier for the billing interval. For example, to make the subscription charge once every 2 weeks, set interval=weekly and interval_count=2.
Number of days the subscription trial period is for. An invoice will not be issued until trial has elapsed.
Specifies a limit to the number of billing cycles for the subscription plan. For example, "limit"=10 would stop billing the customer after the tenth billing cycle.
Frequency of order generation for the subscription plan. Can be monthly, daily, weekly, or yearly.
Multiplier when combined with order interval. For example, to generate an order every two weeks, set interval=weekly and interval_count=2.
Limit to number of orders generated for the purchase option.
Total discount applied to line items.
Total quantity of all line items.
Total quantity of cancelable items on the order.
Total quantity of line items canceled.
Total quantity of line items that can be credited.
Total quantity of items credited on the order.
Total quantity of line items that can be fulfilled.
Total quantity of line items that have been fulfilled.
Total quantity of line items that can be fulfilled by gift card. Applies when item.delivery=giftcard.
Total quantity of items eligible for invoicing on the order.
Total quantity of items invoiced on the order.
Total quantity of line items that can still be returned.
Total quantity of line items that have been returned.
Total quantity of line items that can be fulfilled by shipment. Applies when item.delivery=shipment.
Total quantity of line items that can be fulfilled by subscription. Applies when item.delivery=subscription.
Total shipping weight of all line items.
Total taxes applied to line items.
Indicates line item prices include taxes.
Arbitrary data, typically set in a checkout flow to store custom values. See Frontend API for details.
Internal admin notes, not visible to the customer.
Expandable list of notifications sent on behalf of the order.
Unique incremental order number, assigned automatically using a format configured in general settings.
Indicates the order was paid in full. Always true when payment_marked=true, otherwise depends on the sum of payments.
Expandable link to the parent order.
ID of the parent order.
Expandable list of payments applied to the order.
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.
A message describing the last payment error, if one occurred.
Indicates the order was marked as paid, manually or automatically.
The number of times automatic payment has been attempted.
The method used to resolve automatic payment when all retry attempts are exhausted. Can be blank (do nothing), canceled, or unpaid.
Sum of payments applied to the order, not including refunds.
Expandable list of invoices that haven't been fully paid.
List of promotion IDs applied to the order.
Expandable list of promotions applied to the order.
Indicates the order was marked as refunded, manually or automatically.
Sum of refunds on payments applied to the order.
Indicates the order was fully refunded. Always true when refund_marked=true, otherwise depends on the sum of refunds.
Expandable list of refunds applied to the order.
Total additional credit tax applied to the order from returns, if applicable
Total additional credit amount applied to the order from returns.
Total tax amount of items returned.
Total tax included amount of items returned, separate from line item values.
Total amount of items returned, minus discounts.
Grand total amount applied to the order from returns.
Indicates the order has at least one line item with delivery=shipment.
Shipping discount applied by coupons, promotions, or custom logic.
Total shipping price before discounts.
Object describing the shipping services and rates available for the order. Shipping country must be set before retrieving shipping rates.
Date and time the object was created.
List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here.
Unique code describing the error.
Message describing the error.
Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings.
List of shipping services and rates available.
Unique identifier for the object.
Name of a third-party carrier offering the service, if applicable.
Name of the shipping service.
Price of the shipping service.
Indicates whether shipping service is local pick-up.
Applicable tax code for shipment rating, if applicable.
Shipping tax amount, if applicable.
Indicates shipping total includes taxes, if applicable.
Total shipping price including taxes and discount. Allows for an alternate display style as normally shipment_total and tax_total are shown separately.
Total shipping price after discounts.
Expandable list of shipments created from the order.
The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.
Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Shipping address line 1: street address/PO box/company name.
Shipping address line 2: apartment/suite/unit/building.
Shipping city/district/suburb/town/village.
Shipping state/county/province/region.
Shipping zip/postal code.
Two-letter ISO country code.
Shipping phone number.
ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.
Name of the shipping service. Defaults to shipment_rating.services.name chosen by setting service.
Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.
Indicates shipping details represent the customer's default shipping address.
ID of the customer's address on file.
Expandable link to the customer's address on file.
Indicates whether shipping for local pick-up.
Current status of the order. Can be pending, draft, payment_pending, delivery_pending, hold, complete, or canceled.
Sum of all line items before discounts, taxes and shipping.
Indicates the order has at least one line item with delivery=subscription.
ID of the subscription that spawned the order, if applicable.
Expandable link to the subscription that spawned the order, if applicable.
Total of taxes applied separately from line items.
Total tax amount applied to the order including line items and shipping.
List of taxes applied to the order.
Unique identifier for the object.
Fixed tax amount.
Name of the tax rule. For example "NY Sales Tax".
Priority indicates the order in which a tax rule was applied. Higher priority rules are added on top of other tax rules with a lower priority. Rules with the same priority are calculated excluding each other.
Tax percentage used in calculating the fixed amount.
Indicates the tax applies to shipping.
Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.
Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.
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.
Indicates a draft of line items added to the order.
Indicates the order was made in test mode.
Total shipping price for items credited on the order.
Indicates the customer’s account credit is applied when submitting the order.
Total of all trial prices on the order.
Total of all trial discounts on the order.
Total of all tax for trial items on the order.
The subtotal of all trial items on the order.
The discount for trial items on the order.
The tax of trial items on the order.
The total of trial item tax added to the order's trial_grand_total.
The grand total for trial items on an order.
Entire orders or specific items within an order can be canceled at any time—even after a customer has received their product. The entire order must be canceled if it contains a single item. When an order is canceled, specify the item and quantity. Optionally, you can include the cancel_reason for the cancellation.
Arguments
Unique identifier for the order.
The id of the customer's account.
Expandable link to the customer's account.
Amount of customer's account credit applied for initial payment, if applicable.
Indicates the customer chose to save shipping and billing information to their account when submitting the order.
Indicates the customer was logged into their account when placing the order.
The id of an authorized payment. When "Require payment authorization" is enabled in payment settings, the order will be rejected if initial payment fails.
Expandable link to an authorized payment.
The customer's billing details. Defaults to account.billing. Updating billing will also update the corresponding account billing object.
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. If name is updated, then first_name will be automatically updated as the first word of the name.
Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Billing city/district/suburb/town/village.
Billing state/county/province/region.
Billing zip/postal code.
Two-letter ISO country code.
Billing phone number.
Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.
Credit card billing details used when billing.method=card.
Token generated by Swell Checkout or Stripe.js.
Two-digit number representing the credit card expiration month.
Four-digit number representing the credit card expiration year.
Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Last four digits of the card number.
ID of the payment gateway that should be used to process payments.
Indicates this is a test card.
When used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable, or unchecked.
Indicates billing details represent the customer's default payment method.
ID of the customer's credit card on file, if applicable.
Expandable link to the customer's credit card on file, if applicable.
Amazon billing details used when billing.method=amazon.
Amazon access token provided when a customer authorizes payment in a storefront.
Amazon order reference ID created when a customer initiates payment in a storefront.
PayPal billing details used when billing.method=paypal.
PayPal payer ID provided when a customer authorizes payment in a storefront.
PayPal payment ID created when a customer initiates payment in a storefront.
One-time use reference element used to communicate payment information to a payment gateway.
PayPal authorization ID when a customer makes a payment using their PayPal account.
Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.
Affirm billing details used when billing.method=affirm.
Token used to communicate payment information to the gateway.
Resolve billing details used when billing.method=resolve.
Charge ID returned by the payment gateway for the payment.
Klarna billing details used when billing.method=klarna.
Payment information returned by the gateway during payment initialization.
Ideal billing details used when billing.method=ideal.
Token used to communicate payment information to the gateway.
Bancontact billing details used when billing.method=bancontact.
Payment information returned by the gateway during payment initialization.
Google Pay billing details used when billing.method=google.
One-time use reference element used to communicate payment information to a payment gateway.
Gateway used to facilitate the transaction. For example, gateway=braintree.
Apple Pay billing details used when billing.method=apple.
One-time use reference element used to communicate payment information to a payment gateway.
Gateway used to facilitate the transaction. For example, gateway=braintree.
A message describing the reason for cancelling the order, if applicable.
Indicates the order was completely canceled.
ID of the cart that converted to this order, if applicable.
Expandable link to the cart.
Customer notes provided when placing the order, if any.
Expandable link to the coupon applied to the order.
Coupon code applied to the order.
ID of the coupon applied to the order.
Expandable list of account credit transactions. Balance of these transactions is kept in balance.
Total amount of additional credit applied to the order.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Currency percentage used in calculating the fixed amount.
Date the order was canceled, if applicable.
Date and time the order was created.
When automated payment has failed, this is the date when the system will automatically retry.
Period end date applicable when the order was created from a subscription.
Period start date applicable when the order was created from a subscription.
Date and time the order was last updated.
Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record.
Indicates the order was completely fulfilled. Always true when delivery_marked=true, otherwise depends on the sum of shipments, giftcards, and subscriptions.
Indicates the order was marked as fulfilled, manually or automatically.
Total discount amount.
List of discounts applied to the order.
Unique identifier for the object.
Fixed discount amount.
Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.
Object describing the discount rule details. Custom discounts don't require this value.
Three-letter ISO currency code representing the user's preferred display currency, if applicable.
Locale code representing the user's preferred display locale, if applicable.
Optional message to include with the order when shipping to the recipient.
Indicates the order has at least one line item with delivery=giftcard.
Total payment amount applied to the order from giftcards.
List of gift cards applied to the order.
Unique identifier for the object.
Amount of the gift card balance to spend for initial payment. If not specified, each gift cards will be spent in order until payment is completed.`
Gift card code to apply. A validation error will be returned if the code is not valid.
Fully formatted gift card code for display purposes.
Last four digits of the gift card code.
Expandable link to the gift card record.
Indicates the order is intended as a gift for the recipient.
Grand total including items, shipping and taxes.
Indicates the customer was not logged in when placing the order.
Indicates the order was placed on hold.
Expandable link to the invoice the payment was applied to, if applicable.
List of line items describing the products ordered.
Unique identifier for the item.
List of items offered as a bundle. Defaults to product.bundle_items.
Unique identifier for the object.
ID of the bundle item product.
Method of delivery taken automatically from product.delivery.
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.
Unique identifier for the object.
Name of the product option. Populated automatically when adding an option by ID.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Indicates the option refers to a subscription plan interval.
Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.
Indicates the option refers to a variant aspect.
Expandable link to the bundle item product.
Quantity of the bundle item being ordered. Defaults to 1.
Quantity of the bundle item canceled before fulfillment, if applicable.
Quantity of stock consumed by the bundle item, if applicable.
Quantity of the bundle item that can be fulfilled, if applicable.
Quantity of the bundle item that has been fulfilled, if applicable.
Quantity of the bundle item that can be fulfilled by a gift card. Applies when delivery=giftcard.
Quantity of the bundle item that has been restocked after a return, if applicable.
Quantity of the bundle item that can still be returned after fulfillment, if applicable.
Total quantity of bundle items that have been returned.
Quantity of the bundle item that can be fulfilled by a shipment. Applies when delivery=shipment.
Quantity of the bundle item that can be fulfilled by a subscription. Applies when delivery=subscription.
Total quantity of the bundle item to be fulfilled, calculated as item.quantity * bundle_item.quantity.
Shipping weight taken automatically from product.shipment_weight, if applicable.
Indicates whether the bundle item has stock tracking enabled.
ID of the bundle item variant.
Expandable link to the bundle item variant.
Quantity of bundle items that are able to be canceled.
Quantity of shipments that have been delivered.
Method of delivery taken automatically from product.delivery.
Description used for custom line items, when product is not defined.
Total discount amount divided by quantity.
Total discount applied to the item.
List of discounts applied to the item by coupons, promotions, or custom logic.
Unique identifier for the object. Refers to one of the IDs in the order discounts object.
Fixed discount amount.
Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API for details.
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.
Unique identifier for the object.
Name of the product option. Populated automatically when adding an option by ID.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Indicates the option refers to a subscription plan interval.
Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.
Indicates the option refers to a variant aspect.
Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed.
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.
Total price added to sub total by multiplying quantity and price.
Expandable link to the item product.
ID of the item product.
Quantity of the item being ordered. Defaults to 1.
Quantity of the item canceled before fulfillment, if applicable.
Quantity of stock consumed by the item, if applicable.
Quantity of the item that can be fulfilled, if applicable.
Quantity of the item that has been fulfilled, if applicable.
Quantity of the item that can be fulfilled by a gift card. Applies when delivery=giftcard.
Quantity of the item that has been restocked after a return, if applicable.
Quantity of the item that can still be returned after fulfillment, if applicable.
Quantity of the item that has been returned after fulfillment, if applicable.
Quantity of the item that can be fulfilled by a shipment. Applies when delivery=shipment.
Quantity of the item that can be fulfilled by a subscription. Applies when delivery=subscription.
Shipping weight taken automatically from product.shipment_weight, if applicable.
Indicates whether the item has stock tracking enabled.
Refers to the subscription interval that applies when delivery=subscription.
Refers to the subscription interval count that applies when delivery=subscription.
Indicates the item has been fulfilled as a subscription and marked as paid by reference to this order.
Refers to the subscription trial period that applies when delivery=subscription.
Total tax amount divided by quantity.
Total tax applied to the item.
List of tax rules applied to the item based on tax settings or custom logic.
Unique identifier for the object. Refers to one of the IDs in the order taxes object.
Fixed tax amount.
ID of the item variant, if applicable.
Expandable link to the item variant, if applicable.
Start date for subscription period.
Quantity of items that can be canceled.
Amount of items credited.
Quantity of items eligible to be used with credit.
Quantity of items eligible to be invoiced.
Quantity of invoiced items.
Total discount total for returned items.
Total price of returned items.
Total tax amount of returned items.
Total quantity of items.
Quantity of subscriptions delivered.
Purchase option selected; standard for one-time purchases or subscription for a subscription plan.
Designates the type of purchase option: standard for one-time purchases, subscription for a subscription plan.
ID of the purchase option.
The name of the purchase option.
Price of the purchase option.
ID of the subscription plan, if applicable.
Name of the subscription plan, if applicable.
Billing schedule for the subscription plan, if applicable.
Billing interval for the subscription plan. Can be monthly, weekly, daily, or yearly.
Multiplier for the billing interval. For example, to make the subscription charge once every 2 weeks, set interval=weekly and interval_count=2.
Number of days the subscription trial period is for. An invoice will not be issued until trial has elapsed.
Specifies a limit to the number of billing cycles for the subscription plan. For example, "limit"=10 would stop billing the customer after the tenth billing cycle.
Frequency of order generation for the subscription plan. Can be monthly, daily, weekly, or yearly.
Multiplier when combined with order interval. For example, to generate an order every two weeks, set interval=weekly and interval_count=2.
Limit to number of orders generated for the purchase option.
Total discount applied to line items.
Total quantity of all line items.
Total quantity of cancelable items on the order.
Total quantity of line items canceled.
Total quantity of line items that can be credited.
Total quantity of items credited on the order.
Total quantity of line items that can be fulfilled.
Total quantity of line items that have been fulfilled.
Total quantity of line items that can be fulfilled by gift card. Applies when item.delivery=giftcard.
Total quantity of items eligible for invoicing on the order.
Total quantity of items invoiced on the order.
Total quantity of line items that can still be returned.
Total quantity of line items that have been returned.
Total quantity of line items that can be fulfilled by shipment. Applies when item.delivery=shipment.
Total quantity of line items that can be fulfilled by subscription. Applies when item.delivery=subscription.
Total shipping weight of all line items.
Total taxes applied to line items.
Indicates line item prices include taxes.
Arbitrary data, typically set in a checkout flow to store custom values. See Frontend API for details.
Internal admin notes, not visible to the customer.
Expandable list of notifications sent on behalf of the order.
Unique incremental order number, assigned automatically using a format configured in general settings.
Indicates the order was paid in full. Always true when payment_marked=true, otherwise depends on the sum of payments.
Expandable link to the parent order.
ID of the parent order.
Expandable list of payments applied to the order.
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.
A message describing the last payment error, if one occurred.
Indicates the order was marked as paid, manually or automatically.
The number of times automatic payment has been attempted.
The method used to resolve automatic payment when all retry attempts are exhausted. Can be blank (do nothing), canceled, or unpaid.
Sum of payments applied to the order, not including refunds.
Expandable list of invoices that haven't been fully paid.
List of promotion IDs applied to the order.
Expandable list of promotions applied to the order.
Indicates the order was marked as refunded, manually or automatically.
Sum of refunds on payments applied to the order.
Indicates the order was fully refunded. Always true when refund_marked=true, otherwise depends on the sum of refunds.
Expandable list of refunds applied to the order.
Total additional credit tax applied to the order from returns, if applicable
Total additional credit amount applied to the order from returns.
Total tax amount of items returned.
Total tax included amount of items returned, separate from line item values.
Total amount of items returned, minus discounts.
Grand total amount applied to the order from returns.
Indicates the order has at least one line item with delivery=shipment.
Shipping discount applied by coupons, promotions, or custom logic.
Total shipping price before discounts.
Object describing the shipping services and rates available for the order. Shipping country must be set before retrieving shipping rates.
Date and time the object was created.
List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here.
Unique code describing the error.
Message describing the error.
Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings.
List of shipping services and rates available.
Unique identifier for the object.
Name of a third-party carrier offering the service, if applicable.
Name of the shipping service.
Price of the shipping service.
Indicates whether shipping service is local pick-up.
Applicable tax code for shipment rating, if applicable.
Shipping tax amount, if applicable.
Indicates shipping total includes taxes, if applicable.
Total shipping price including taxes and discount. Allows for an alternate display style as normally shipment_total and tax_total are shown separately.
Total shipping price after discounts.
Expandable list of shipments created from the order.
The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.
Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Shipping address line 1: street address/PO box/company name.
Shipping address line 2: apartment/suite/unit/building.
Shipping city/district/suburb/town/village.
Shipping state/county/province/region.
Shipping zip/postal code.
Two-letter ISO country code.
Shipping phone number.
ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.
Name of the shipping service. Defaults to shipment_rating.services.name chosen by setting service.
Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.
Indicates shipping details represent the customer's default shipping address.
ID of the customer's address on file.
Expandable link to the customer's address on file.
Indicates whether shipping for local pick-up.
Current status of the order. Can be pending, draft, payment_pending, delivery_pending, hold, complete, or canceled.
Sum of all line items before discounts, taxes and shipping.
Indicates the order has at least one line item with delivery=subscription.
ID of the subscription that spawned the order, if applicable.
Expandable link to the subscription that spawned the order, if applicable.
Total of taxes applied separately from line items.
Total tax amount applied to the order including line items and shipping.
List of taxes applied to the order.
Unique identifier for the object.
Fixed tax amount.
Name of the tax rule. For example "NY Sales Tax".
Priority indicates the order in which a tax rule was applied. Higher priority rules are added on top of other tax rules with a lower priority. Rules with the same priority are calculated excluding each other.
Tax percentage used in calculating the fixed amount.
Indicates the tax applies to shipping.
Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.
Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.
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.
Indicates a draft of line items added to the order.
Indicates the order was made in test mode.
Total shipping price for items credited on the order.
Indicates the customer’s account credit is applied when submitting the order.
Total of all trial prices on the order.
Total of all trial discounts on the order.
Total of all tax for trial items on the order.
The subtotal of all trial items on the order.
The discount for trial items on the order.
The tax of trial items on the order.
The total of trial item tax added to the order's trial_grand_total.
The grand total for trial items on an order.
Typically, a return is initiated by a customer. The return is associated with the order_id and the items being returned. Once shipped, a return can optionally be updated with the return's shipping carrier, service, and the tracking_code to keep track of the return shipment's transit to the return address.
Returns can also be facilitated through the dashboard by selecting an order and choosing Actions > Return items—specify the return items and quantity, refund, restocking fee if applicable, and optionally add notes.
Arguments
Unique identifier for the order.
The id of the customer's account.
Expandable link to the customer's account.
Amount of customer's account credit applied for initial payment, if applicable.
Indicates the customer chose to save shipping and billing information to their account when submitting the order.
Indicates the customer was logged into their account when placing the order.
The id of an authorized payment. When "Require payment authorization" is enabled in payment settings, the order will be rejected if initial payment fails.
Expandable link to an authorized payment.
The customer's billing details. Defaults to account.billing. Updating billing will also update the corresponding account billing object.
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. If name is updated, then first_name will be automatically updated as the first word of the name.
Billing last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Billing address line 1: street address/PO box/company name.
Billing address line 2: apartment/suite/unit/building.
Billing city/district/suburb/town/village.
Billing state/county/province/region.
Billing zip/postal code.
Two-letter ISO country code.
Billing phone number.
Method of payment. Can be card, account, amazon, paypal, or any one of the manual methods defined in payment settings.
Credit card billing details used when billing.method=card.
Token generated by Swell Checkout or Stripe.js.
Two-digit number representing the credit card expiration month.
Four-digit number representing the credit card expiration year.
Credit card brand. Can be American Express, Diners Club, Discover, JCB, MasterCard, UnionPay, Visa, or Unknown.
Last four digits of the card number.
ID of the payment gateway that should be used to process payments.
Indicates this is a test card.
When used with a payment gateway that performs address checks and address1 was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs address checks and zip was provided, can be pass, fail, unavailable, or unchecked.
When used with a payment gateway that performs CVC code checks and cvc was provided, can be pass, fail, unavailable, or unchecked.
Indicates billing details represent the customer's default payment method.
ID of the customer's credit card on file, if applicable.
Expandable link to the customer's credit card on file, if applicable.
Amazon billing details used when billing.method=amazon.
Amazon access token provided when a customer authorizes payment in a storefront.
Amazon order reference ID created when a customer initiates payment in a storefront.
PayPal billing details used when billing.method=paypal.
PayPal payer ID provided when a customer authorizes payment in a storefront.
PayPal payment ID created when a customer initiates payment in a storefront.
One-time use reference element used to communicate payment information to a payment gateway.
PayPal authorization ID when a customer makes a payment using their PayPal account.
Stores the necessary information about the payment. This is typically the payment ID returned by the gateway after payment is initialized.
Affirm billing details used when billing.method=affirm.
Token used to communicate payment information to the gateway.
Resolve billing details used when billing.method=resolve.
Charge ID returned by the payment gateway for the payment.
Klarna billing details used when billing.method=klarna.
Payment information returned by the gateway during payment initialization.
Ideal billing details used when billing.method=ideal.
Token used to communicate payment information to the gateway.
Bancontact billing details used when billing.method=bancontact.
Payment information returned by the gateway during payment initialization.
Google Pay billing details used when billing.method=google.
One-time use reference element used to communicate payment information to a payment gateway.
Gateway used to facilitate the transaction. For example, gateway=braintree.
Apple Pay billing details used when billing.method=apple.
One-time use reference element used to communicate payment information to a payment gateway.
Gateway used to facilitate the transaction. For example, gateway=braintree.
A message describing the reason for cancelling the order, if applicable.
Indicates the order was completely canceled.
ID of the cart that converted to this order, if applicable.
Expandable link to the cart.
Customer notes provided when placing the order, if any.
Expandable link to the coupon applied to the order.
Coupon code applied to the order.
ID of the coupon applied to the order.
Expandable list of account credit transactions. Balance of these transactions is kept in balance.
Total amount of additional credit applied to the order.
Three-letter ISO currency code in uppercase. Defaults to the store's base currency.
Currency percentage used in calculating the fixed amount.
Date the order was canceled, if applicable.
Date and time the order was created.
When automated payment has failed, this is the date when the system will automatically retry.
Period end date applicable when the order was created from a subscription.
Period start date applicable when the order was created from a subscription.
Date and time the order was last updated.
Date the order webhook first failed, if applicable. Value is unset after an order webhook is successfully returned for the record.
Indicates the order was completely fulfilled. Always true when delivery_marked=true, otherwise depends on the sum of shipments, giftcards, and subscriptions.
Indicates the order was marked as fulfilled, manually or automatically.
Total discount amount.
List of discounts applied to the order.
Unique identifier for the object.
Fixed discount amount.
Type of discount. Can be coupon or promo-<id> referring to the source of the discount. Custom discounts don't require this value.
Object describing the discount rule details. Custom discounts don't require this value.
Three-letter ISO currency code representing the user's preferred display currency, if applicable.
Locale code representing the user's preferred display locale, if applicable.
Optional message to include with the order when shipping to the recipient.
Indicates the order has at least one line item with delivery=giftcard.
Total payment amount applied to the order from giftcards.
List of gift cards applied to the order.
Unique identifier for the object.
Amount of the gift card balance to spend for initial payment. If not specified, each gift cards will be spent in order until payment is completed.`
Gift card code to apply. A validation error will be returned if the code is not valid.
Fully formatted gift card code for display purposes.
Last four digits of the gift card code.
Expandable link to the gift card record.
Indicates the order is intended as a gift for the recipient.
Grand total including items, shipping and taxes.
Indicates the customer was not logged in when placing the order.
Indicates the order was placed on hold.
Expandable link to the invoice the payment was applied to, if applicable.
List of line items describing the products ordered.
Unique identifier for the item.
List of items offered as a bundle. Defaults to product.bundle_items.
Unique identifier for the object.
ID of the bundle item product.
Method of delivery taken automatically from product.delivery.
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.
Unique identifier for the object.
Name of the product option. Populated automatically when adding an option by ID.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Indicates the option refers to a subscription plan interval.
Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.
Indicates the option refers to a variant aspect.
Expandable link to the bundle item product.
Quantity of the bundle item being ordered. Defaults to 1.
Quantity of the bundle item canceled before fulfillment, if applicable.
Quantity of stock consumed by the bundle item, if applicable.
Quantity of the bundle item that can be fulfilled, if applicable.
Quantity of the bundle item that has been fulfilled, if applicable.
Quantity of the bundle item that can be fulfilled by a gift card. Applies when delivery=giftcard.
Quantity of the bundle item that has been restocked after a return, if applicable.
Quantity of the bundle item that can still be returned after fulfillment, if applicable.
Total quantity of bundle items that have been returned.
Quantity of the bundle item that can be fulfilled by a shipment. Applies when delivery=shipment.
Quantity of the bundle item that can be fulfilled by a subscription. Applies when delivery=subscription.
Total quantity of the bundle item to be fulfilled, calculated as item.quantity * bundle_item.quantity.
Shipping weight taken automatically from product.shipment_weight, if applicable.
Indicates whether the bundle item has stock tracking enabled.
ID of the bundle item variant.
Expandable link to the bundle item variant.
Quantity of bundle items that are able to be canceled.
Quantity of shipments that have been delivered.
Method of delivery taken automatically from product.delivery.
Description used for custom line items, when product is not defined.
Total discount amount divided by quantity.
Total discount applied to the item.
List of discounts applied to the item by coupons, promotions, or custom logic.
Unique identifier for the object. Refers to one of the IDs in the order discounts object.
Fixed discount amount.
Arbitrary item data, typically set in a checkout flow to store custom values. See Storefront API for details.
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.
Unique identifier for the object.
Name of the product option. Populated automatically when adding an option by ID.
Additional price added onto the base price of the product.
Additional shipping weight added onto the base weight of the product.
Indicates the option refers to a subscription plan interval.
Name value of the product option. When adding to the order, specify either the product option value id or name (case-insensitive) to identify the value.
Indicates the option refers to a variant aspect.
Original item price used internally to determine if the item price was overridden and should be automatically updated when item options are changed.
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.
Total price added to sub total by multiplying quantity and price.
Expandable link to the item product.
ID of the item product.
Quantity of the item being ordered. Defaults to 1.
Quantity of the item canceled before fulfillment, if applicable.
Quantity of stock consumed by the item, if applicable.
Quantity of the item that can be fulfilled, if applicable.
Quantity of the item that has been fulfilled, if applicable.
Quantity of the item that can be fulfilled by a gift card. Applies when delivery=giftcard.
Quantity of the item that has been restocked after a return, if applicable.
Quantity of the item that can still be returned after fulfillment, if applicable.
Quantity of the item that has been returned after fulfillment, if applicable.
Quantity of the item that can be fulfilled by a shipment. Applies when delivery=shipment.
Quantity of the item that can be fulfilled by a subscription. Applies when delivery=subscription.
Shipping weight taken automatically from product.shipment_weight, if applicable.
Indicates whether the item has stock tracking enabled.
Refers to the subscription interval that applies when delivery=subscription.
Refers to the subscription interval count that applies when delivery=subscription.
Indicates the item has been fulfilled as a subscription and marked as paid by reference to this order.
Refers to the subscription trial period that applies when delivery=subscription.
Total tax amount divided by quantity.
Total tax applied to the item.
List of tax rules applied to the item based on tax settings or custom logic.
Unique identifier for the object. Refers to one of the IDs in the order taxes object.
Fixed tax amount.
ID of the item variant, if applicable.
Expandable link to the item variant, if applicable.
Start date for subscription period.
Quantity of items that can be canceled.
Amount of items credited.
Quantity of items eligible to be used with credit.
Quantity of items eligible to be invoiced.
Quantity of invoiced items.
Total discount total for returned items.
Total price of returned items.
Total tax amount of returned items.
Total quantity of items.
Quantity of subscriptions delivered.
Purchase option selected; standard for one-time purchases or subscription for a subscription plan.
Designates the type of purchase option: standard for one-time purchases, subscription for a subscription plan.
ID of the purchase option.
The name of the purchase option.
Price of the purchase option.
ID of the subscription plan, if applicable.
Name of the subscription plan, if applicable.
Billing schedule for the subscription plan, if applicable.
Billing interval for the subscription plan. Can be monthly, weekly, daily, or yearly.
Multiplier for the billing interval. For example, to make the subscription charge once every 2 weeks, set interval=weekly and interval_count=2.
Number of days the subscription trial period is for. An invoice will not be issued until trial has elapsed.
Specifies a limit to the number of billing cycles for the subscription plan. For example, "limit"=10 would stop billing the customer after the tenth billing cycle.
Frequency of order generation for the subscription plan. Can be monthly, daily, weekly, or yearly.
Multiplier when combined with order interval. For example, to generate an order every two weeks, set interval=weekly and interval_count=2.
Limit to number of orders generated for the purchase option.
Total discount applied to line items.
Total quantity of all line items.
Total quantity of cancelable items on the order.
Total quantity of line items canceled.
Total quantity of line items that can be credited.
Total quantity of items credited on the order.
Total quantity of line items that can be fulfilled.
Total quantity of line items that have been fulfilled.
Total quantity of line items that can be fulfilled by gift card. Applies when item.delivery=giftcard.
Total quantity of items eligible for invoicing on the order.
Total quantity of items invoiced on the order.
Total quantity of line items that can still be returned.
Total quantity of line items that have been returned.
Total quantity of line items that can be fulfilled by shipment. Applies when item.delivery=shipment.
Total quantity of line items that can be fulfilled by subscription. Applies when item.delivery=subscription.
Total shipping weight of all line items.
Total taxes applied to line items.
Indicates line item prices include taxes.
Arbitrary data, typically set in a checkout flow to store custom values. See Frontend API for details.
Internal admin notes, not visible to the customer.
Expandable list of notifications sent on behalf of the order.
Unique incremental order number, assigned automatically using a format configured in general settings.
Indicates the order was paid in full. Always true when payment_marked=true, otherwise depends on the sum of payments.
Expandable link to the parent order.
ID of the parent order.
Expandable list of payments applied to the order.
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.
A message describing the last payment error, if one occurred.
Indicates the order was marked as paid, manually or automatically.
The number of times automatic payment has been attempted.
The method used to resolve automatic payment when all retry attempts are exhausted. Can be blank (do nothing), canceled, or unpaid.
Sum of payments applied to the order, not including refunds.
Expandable list of invoices that haven't been fully paid.
List of promotion IDs applied to the order.
Expandable list of promotions applied to the order.
Indicates the order was marked as refunded, manually or automatically.
Sum of refunds on payments applied to the order.
Indicates the order was fully refunded. Always true when refund_marked=true, otherwise depends on the sum of refunds.
Expandable list of refunds applied to the order.
Total additional credit tax applied to the order from returns, if applicable
Total additional credit amount applied to the order from returns.
Total tax amount of items returned.
Total tax included amount of items returned, separate from line item values.
Total amount of items returned, minus discounts.
Grand total amount applied to the order from returns.
Indicates the order has at least one line item with delivery=shipment.
Shipping discount applied by coupons, promotions, or custom logic.
Total shipping price before discounts.
Object describing the shipping services and rates available for the order. Shipping country must be set before retrieving shipping rates.
Date and time the object was created.
List of errors generated while retrieving rates, if any. When using third-party shipping services, any system errors will be listed here.
Unique code describing the error.
Message describing the error.
Unique fingerprint identifying the parameters used to calculate shipping rates. Rates should always be the same given the same parameters and shipping settings.
List of shipping services and rates available.
Unique identifier for the object.
Name of a third-party carrier offering the service, if applicable.
Name of the shipping service.
Price of the shipping service.
Indicates whether shipping service is local pick-up.
Applicable tax code for shipment rating, if applicable.
Shipping tax amount, if applicable.
Indicates shipping total includes taxes, if applicable.
Total shipping price including taxes and discount. Allows for an alternate display style as normally shipment_total and tax_total are shown separately.
Total shipping price after discounts.
Expandable list of shipments created from the order.
The customer's shipping details. Defaults to account.shipping. Updating shipping will also update the corresponding account shipping object.
Shipping full name. If first_name or last_name are updated, then name will be automatically updated as a combination of first/last.
Shipping first name. If name is updated, then first_name will be automatically updated as the first word of the name.
Shipping last name. If name is updated, then last_name will be automatically updated as the last words of the name.
Shipping address line 1: street address/PO box/company name.
Shipping address line 2: apartment/suite/unit/building.
Shipping city/district/suburb/town/village.
Shipping state/county/province/region.
Shipping zip/postal code.
Two-letter ISO country code.
Shipping phone number.
ID of a shipping service as configured in shipment settings. Normally, this would be applied after retrieving shipping rates by using one of the shipment_rating.services.id values.
Name of the shipping service. Defaults to shipment_rating.services.name chosen by setting service.
Price of the shipping service. Defaults to shipment_rating.services.price chosen by setting service.
Indicates shipping details represent the customer's default shipping address.
ID of the customer's address on file.
Expandable link to the customer's address on file.
Indicates whether shipping for local pick-up.
Current status of the order. Can be pending, draft, payment_pending, delivery_pending, hold, complete, or canceled.
Sum of all line items before discounts, taxes and shipping.
Indicates the order has at least one line item with delivery=subscription.
ID of the subscription that spawned the order, if applicable.
Expandable link to the subscription that spawned the order, if applicable.
Total of taxes applied separately from line items.
Total tax amount applied to the order including line items and shipping.
List of taxes applied to the order.
Unique identifier for the object.
Fixed tax amount.
Name of the tax rule. For example "NY Sales Tax".
Priority indicates the order in which a tax rule was applied. Higher priority rules are added on top of other tax rules with a lower priority. Rules with the same priority are calculated excluding each other.
Tax percentage used in calculating the fixed amount.
Indicates the tax applies to shipping.
Number of failed order webhook attempts, if applicable. Value is unset after an order webhook is successfully returned for the record.
Text response of the last failed order webhook attempt, if applicable. Value is unset after an order webhook is successfully returned for the record.
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.
Indicates a draft of line items added to the order.
Indicates the order was made in test mode.
Total shipping price for items credited on the order.
Indicates the customer’s account credit is applied when submitting the order.
Total of all trial prices on the order.
Total of all trial discounts on the order.
Total of all tax for trial items on the order.
The subtotal of all trial items on the order.
The discount for trial items on the order.
The tax of trial items on the order.
The total of trial item tax added to the order's trial_grand_total.
The grand total for trial items on an order.