Create Return

JS SDK

import Switchyard from "@switchyard/js-sdk"

export const sdk = new Medusa({
  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
  debug: import.meta.env.DEV,
  auth: {
    type: "session",
  },
})

sdk.admin.return.initiateRequest({
  order_id: "order_123",
})
.then(({ return }) => {
  console.log(return)
})

{
  "order": {
    "id": "<string>",
    "version": 123,
    "status": "canceled",
    "currency_code": "usd",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "original_item_total": 123,
    "original_item_subtotal": 123,
    "original_item_tax_total": 123,
    "item_total": 123,
    "item_subtotal": 123,
    "item_tax_total": 123,
    "original_total": 123,
    "original_subtotal": 123,
    "original_tax_total": 123,
    "total": 123,
    "subtotal": 123,
    "tax_total": 123,
    "discount_subtotal": 123,
    "discount_total": 123,
    "discount_tax_total": 123,
    "gift_card_total": 123,
    "gift_card_tax_total": 123,
    "shipping_total": 123,
    "shipping_subtotal": 123,
    "shipping_tax_total": 123,
    "original_shipping_total": 123,
    "original_shipping_subtotal": 123,
    "original_shipping_tax_total": 123,
    "display_id": 123,
    "credit_line_total": 123,
    "item_discount_total": 123,
    "shipping_discount_total": 123,
    "order_change": {},
    "region_id": "<string>",
    "customer_id": "<string>",
    "sales_channel_id": "<string>",
    "email": "jsmith@example.com",
    "shipping_address": {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "customer_id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "phone": "<string>",
      "company": "<string>",
      "address_1": "<string>",
      "address_2": "<string>",
      "city": "<string>",
      "country_code": "us",
      "province": "us-ca",
      "postal_code": "<string>",
      "metadata": {}
    },
    "billing_address": {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "customer_id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "phone": "<string>",
      "company": "<string>",
      "address_1": "<string>",
      "address_2": "<string>",
      "city": "<string>",
      "country_code": "us",
      "province": "us-ca",
      "postal_code": "<string>",
      "metadata": {}
    },
    "items": [
      {
        "id": "<string>",
        "title": "<string>",
        "requires_shipping": true,
        "is_discountable": true,
        "is_tax_inclusive": true,
        "unit_price": 123,
        "quantity": 123,
        "detail": {
          "id": "<string>",
          "item_id": "<string>",
          "item": {},
          "quantity": 123,
          "fulfilled_quantity": 123,
          "delivered_quantity": 123,
          "shipped_quantity": 123,
          "return_requested_quantity": 123,
          "return_received_quantity": 123,
          "return_dismissed_quantity": 123,
          "written_off_quantity": 123,
          "metadata": {},
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        },
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "original_total": 123,
        "original_subtotal": 123,
        "original_tax_total": 123,
        "item_total": 123,
        "item_subtotal": 123,
        "item_tax_total": 123,
        "total": 123,
        "subtotal": 123,
        "tax_total": 123,
        "discount_total": 123,
        "discount_tax_total": 123,
        "refundable_total": 123,
        "refundable_total_per_unit": 123,
        "is_giftcard": true,
        "subtitle": "<string>",
        "thumbnail": "<string>",
        "variant_id": "<string>",
        "product_id": "<string>",
        "product_title": "<string>",
        "product_description": "<string>",
        "product_subtitle": "<string>",
        "product_type": "<string>",
        "product_collection": "<string>",
        "product_handle": "<string>",
        "variant_sku": "<string>",
        "variant_barcode": "<string>",
        "variant_title": "<string>",
        "variant_option_values": {
          "Color": "Red"
        },
        "compare_at_unit_price": 123,
        "tax_lines": [
          {
            "item": {},
            "item_id": "<string>",
            "total": 123,
            "subtotal": 123,
            "id": "<string>",
            "code": "<string>",
            "rate": 123,
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "description": "<string>",
            "tax_rate_id": "<string>",
            "provider_id": "<string>"
          }
        ],
        "adjustments": [
          {
            "item": {},
            "item_id": "<string>",
            "id": "<string>",
            "amount": 123,
            "order_id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "code": "<string>",
            "description": "<string>",
            "promotion_id": "<string>",
            "provider_id": "<string>"
          }
        ],
        "metadata": {},
        "product_type_id": "<string>"
      }
    ],
    "shipping_methods": [
      {
        "id": "<string>",
        "order_id": "<string>",
        "name": "<string>",
        "amount": 123,
        "is_tax_inclusive": true,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "original_total": 123,
        "original_subtotal": 123,
        "original_tax_total": 123,
        "total": 123,
        "subtotal": 123,
        "tax_total": 123,
        "discount_total": 123,
        "discount_tax_total": 123,
        "description": "<string>",
        "shipping_option_id": "<string>",
        "data": {},
        "metadata": {},
        "tax_lines": [
          {
            "shipping_method": {},
            "shipping_method_id": "<string>",
            "total": 123,
            "subtotal": 123,
            "id": "<string>",
            "code": "<string>",
            "rate": 123,
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "description": "<string>",
            "tax_rate_id": "<string>",
            "provider_id": "<string>"
          }
        ],
        "adjustments": [
          {
            "shipping_method": {},
            "shipping_method_id": "<string>",
            "id": "<string>",
            "amount": 123,
            "order_id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "code": "<string>",
            "description": "<string>",
            "promotion_id": "<string>",
            "provider_id": "<string>"
          }
        ]
      }
    ],
    "transactions": [
      {
        "id": "<string>",
        "order_id": "<string>",
        "amount": 123,
        "currency_code": "usd",
        "reference": "capture",
        "reference_id": "<string>",
        "metadata": {},
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "order": {},
        "version": 123
      }
    ],
    "summary": {
      "pending_difference": 123,
      "current_order_total": 123,
      "original_order_total": 123,
      "transaction_total": 123,
      "paid_total": 123,
      "refunded_total": 123,
      "credit_line_total": 123,
      "accounting_total": 123,
      "raw_pending_difference": {},
      "raw_current_order_total": {},
      "raw_original_order_total": {},
      "raw_transaction_total": {},
      "raw_paid_total": {},
      "raw_refunded_total": {},
      "raw_credit_line_total": {},
      "raw_accounting_total": {}
    },
    "metadata": {},
    "canceled_at": "2023-11-07T05:31:56Z",
    "credit_lines": [
      {
        "id": "<string>",
        "order_id": "<string>",
        "order": {},
        "reference": "<string>",
        "reference_id": "<string>",
        "metadata": {},
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "amount": 123
      }
    ],
    "is_draft_order": true,
    "deleted_at": "2023-11-07T05:31:56Z",
    "custom_display_id": "<string>"
  },
  "return": {
    "id": "<string>",
    "order_id": "<string>",
    "items": [
      {
        "id": "<string>",
        "quantity": 123,
        "received_quantity": 123,
        "damaged_quantity": 123,
        "item_id": "<string>",
        "return_id": "<string>",
        "reason_id": "<string>",
        "note": "<string>",
        "metadata": {}
      }
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "canceled_at": "2023-11-07T05:31:56Z",
    "order_version": 123,
    "display_id": 123,
    "received_at": "<string>",
    "status": "canceled",
    "refund_amount": 123,
    "exchange_id": "<string>",
    "location_id": "<string>",
    "claim_id": "<string>",
    "no_notification": true
  }
}

POST

admin

returns

JS SDK

import Switchyard from "@switchyard/js-sdk"

export const sdk = new Medusa({
  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
  debug: import.meta.env.DEV,
  auth: {
    type: "session",
  },
})

sdk.admin.return.initiateRequest({
  order_id: "order_123",
})
.then(({ return }) => {
  console.log(return)
})

{
  "order": {
    "id": "<string>",
    "version": 123,
    "status": "canceled",
    "currency_code": "usd",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "original_item_total": 123,
    "original_item_subtotal": 123,
    "original_item_tax_total": 123,
    "item_total": 123,
    "item_subtotal": 123,
    "item_tax_total": 123,
    "original_total": 123,
    "original_subtotal": 123,
    "original_tax_total": 123,
    "total": 123,
    "subtotal": 123,
    "tax_total": 123,
    "discount_subtotal": 123,
    "discount_total": 123,
    "discount_tax_total": 123,
    "gift_card_total": 123,
    "gift_card_tax_total": 123,
    "shipping_total": 123,
    "shipping_subtotal": 123,
    "shipping_tax_total": 123,
    "original_shipping_total": 123,
    "original_shipping_subtotal": 123,
    "original_shipping_tax_total": 123,
    "display_id": 123,
    "credit_line_total": 123,
    "item_discount_total": 123,
    "shipping_discount_total": 123,
    "order_change": {},
    "region_id": "<string>",
    "customer_id": "<string>",
    "sales_channel_id": "<string>",
    "email": "jsmith@example.com",
    "shipping_address": {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "customer_id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "phone": "<string>",
      "company": "<string>",
      "address_1": "<string>",
      "address_2": "<string>",
      "city": "<string>",
      "country_code": "us",
      "province": "us-ca",
      "postal_code": "<string>",
      "metadata": {}
    },
    "billing_address": {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "customer_id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "phone": "<string>",
      "company": "<string>",
      "address_1": "<string>",
      "address_2": "<string>",
      "city": "<string>",
      "country_code": "us",
      "province": "us-ca",
      "postal_code": "<string>",
      "metadata": {}
    },
    "items": [
      {
        "id": "<string>",
        "title": "<string>",
        "requires_shipping": true,
        "is_discountable": true,
        "is_tax_inclusive": true,
        "unit_price": 123,
        "quantity": 123,
        "detail": {
          "id": "<string>",
          "item_id": "<string>",
          "item": {},
          "quantity": 123,
          "fulfilled_quantity": 123,
          "delivered_quantity": 123,
          "shipped_quantity": 123,
          "return_requested_quantity": 123,
          "return_received_quantity": 123,
          "return_dismissed_quantity": 123,
          "written_off_quantity": 123,
          "metadata": {},
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        },
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "original_total": 123,
        "original_subtotal": 123,
        "original_tax_total": 123,
        "item_total": 123,
        "item_subtotal": 123,
        "item_tax_total": 123,
        "total": 123,
        "subtotal": 123,
        "tax_total": 123,
        "discount_total": 123,
        "discount_tax_total": 123,
        "refundable_total": 123,
        "refundable_total_per_unit": 123,
        "is_giftcard": true,
        "subtitle": "<string>",
        "thumbnail": "<string>",
        "variant_id": "<string>",
        "product_id": "<string>",
        "product_title": "<string>",
        "product_description": "<string>",
        "product_subtitle": "<string>",
        "product_type": "<string>",
        "product_collection": "<string>",
        "product_handle": "<string>",
        "variant_sku": "<string>",
        "variant_barcode": "<string>",
        "variant_title": "<string>",
        "variant_option_values": {
          "Color": "Red"
        },
        "compare_at_unit_price": 123,
        "tax_lines": [
          {
            "item": {},
            "item_id": "<string>",
            "total": 123,
            "subtotal": 123,
            "id": "<string>",
            "code": "<string>",
            "rate": 123,
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "description": "<string>",
            "tax_rate_id": "<string>",
            "provider_id": "<string>"
          }
        ],
        "adjustments": [
          {
            "item": {},
            "item_id": "<string>",
            "id": "<string>",
            "amount": 123,
            "order_id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "code": "<string>",
            "description": "<string>",
            "promotion_id": "<string>",
            "provider_id": "<string>"
          }
        ],
        "metadata": {},
        "product_type_id": "<string>"
      }
    ],
    "shipping_methods": [
      {
        "id": "<string>",
        "order_id": "<string>",
        "name": "<string>",
        "amount": 123,
        "is_tax_inclusive": true,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "original_total": 123,
        "original_subtotal": 123,
        "original_tax_total": 123,
        "total": 123,
        "subtotal": 123,
        "tax_total": 123,
        "discount_total": 123,
        "discount_tax_total": 123,
        "description": "<string>",
        "shipping_option_id": "<string>",
        "data": {},
        "metadata": {},
        "tax_lines": [
          {
            "shipping_method": {},
            "shipping_method_id": "<string>",
            "total": 123,
            "subtotal": 123,
            "id": "<string>",
            "code": "<string>",
            "rate": 123,
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "description": "<string>",
            "tax_rate_id": "<string>",
            "provider_id": "<string>"
          }
        ],
        "adjustments": [
          {
            "shipping_method": {},
            "shipping_method_id": "<string>",
            "id": "<string>",
            "amount": 123,
            "order_id": "<string>",
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "code": "<string>",
            "description": "<string>",
            "promotion_id": "<string>",
            "provider_id": "<string>"
          }
        ]
      }
    ],
    "transactions": [
      {
        "id": "<string>",
        "order_id": "<string>",
        "amount": 123,
        "currency_code": "usd",
        "reference": "capture",
        "reference_id": "<string>",
        "metadata": {},
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "order": {},
        "version": 123
      }
    ],
    "summary": {
      "pending_difference": 123,
      "current_order_total": 123,
      "original_order_total": 123,
      "transaction_total": 123,
      "paid_total": 123,
      "refunded_total": 123,
      "credit_line_total": 123,
      "accounting_total": 123,
      "raw_pending_difference": {},
      "raw_current_order_total": {},
      "raw_original_order_total": {},
      "raw_transaction_total": {},
      "raw_paid_total": {},
      "raw_refunded_total": {},
      "raw_credit_line_total": {},
      "raw_accounting_total": {}
    },
    "metadata": {},
    "canceled_at": "2023-11-07T05:31:56Z",
    "credit_lines": [
      {
        "id": "<string>",
        "order_id": "<string>",
        "order": {},
        "reference": "<string>",
        "reference_id": "<string>",
        "metadata": {},
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "amount": 123
      }
    ],
    "is_draft_order": true,
    "deleted_at": "2023-11-07T05:31:56Z",
    "custom_display_id": "<string>"
  },
  "return": {
    "id": "<string>",
    "order_id": "<string>",
    "items": [
      {
        "id": "<string>",
        "quantity": 123,
        "received_quantity": 123,
        "damaged_quantity": 123,
        "item_id": "<string>",
        "return_id": "<string>",
        "reason_id": "<string>",
        "note": "<string>",
        "metadata": {}
      }
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "canceled_at": "2023-11-07T05:31:56Z",
    "order_version": 123,
    "display_id": 123,
    "received_at": "<string>",
    "status": "canceled",
    "refund_amount": 123,
    "exchange_id": "<string>",
    "location_id": "<string>",
    "claim_id": "<string>",
    "no_notification": true
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

fields

string

Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

Body

application/json

The return's details.

order_id

string

required

The ID of the order the return belongs to.

location_id

string

The ID of the location the items are returned to.

description

string

The return's description.

internal_note

string

A note viewed only by admin users.

no_notification

boolean

Whether to send the customer a notification about the created return.

metadata

object

The return's metadata, can hold custom key-value pairs.

Response

The order return details.

order

object

required

The order change's order.

Show child attributes

order.id

string

required

The order's ID.

order.version

number

required

The order's version.

order.status

enum<string>

required

The order's status.

Available options:

canceled,

requires_action,

pending,

completed,

draft,

archived

order.currency_code

string

required

The order's currency code.

Example:

"usd"

order.created_at

string<date-time>

required

The date the order was created.

order.updated_at

string<date-time>

required

The date the order was updated.

order.original_item_total

number

required

The order items' total including taxes, excluding promotions.

order.original_item_subtotal

number

required

The order items' total excluding taxes, including promotions.

order.original_item_tax_total

number

required

The taxes total for order items, excluding promotions.

order.item_total

number

required

The order items' total including taxes and promotions.

order.item_subtotal

number

required

The order items' total excluding taxes, including promotions.

order.item_tax_total

number

required

The tax total of the order items including promotions.

order.original_total

number

required

The order's total including taxes, excluding promotions.

order.original_subtotal

number

required

The order's total excluding taxes, including promotions.

order.original_tax_total

number

required

The tax total of the order excluding promotions.

order.total

number

required

The order's total including taxes and promotions.

order.subtotal

number

required

The order's subtotal excluding taxes, including promotions.

order.tax_total

number

required

The tax total of the order including promotions.

order.discount_subtotal

number

required

The total discount excluding taxes.

order.discount_total

number

required

The total discount including taxes.

order.discount_tax_total

number

required

The tax total applied on the discount.

order.gift_card_total

number

required

The order's gift card total.

order.gift_card_tax_total

number

required

The order's gift card tax total.

order.shipping_total

number

required

The order's shipping total including taxes and promotions.

order.shipping_subtotal

number

required

The order's shipping total excluding taxes, including promotions.

order.shipping_tax_total

number

required

The total taxes of the order's shipping including taxes.

order.original_shipping_total

number

required

The order's shipping total including taxes, excluding promotions.

order.original_shipping_subtotal

number

required

The order's shipping total excluding taxes, including promotions.

order.original_shipping_tax_total

number

required

The total taxes of the order's shipping excluding promotions.

order.display_id

number

required

The order's display ID.

order.credit_line_total

number

required

The order's credit line total.

order.item_discount_total

number

required

The total discount amount applied on the order's items.

order.shipping_discount_total

number

required

The total discount amount applied on the order's shipping.

order.order_change

object

order.region_id

string

The ID of the region the order belongs to.

order.customer_id

string

The ID of the customer that placed the order.

order.sales_channel_id

string

The ID of the sales channel the order was placed in.

order.email

string<email>

The email of the customer that placed the order.

order.shipping_address

object

The address's details.

Show child attributes

order.shipping_address.id

string

required

The address's ID.

order.shipping_address.created_at

string<date-time>

required

The date the address was created.

order.shipping_address.updated_at

string<date-time>

required

The date the address was updated.

order.shipping_address.customer_id

string

The ID of the customer the address belongs to.

order.shipping_address.first_name

string

The address's first name.

order.shipping_address.last_name

string

The address's last name.

order.shipping_address.phone

string

The address's phone.

order.shipping_address.company

string

The address's company.

order.shipping_address.address_1

string

The address's first line.

order.shipping_address.address_2

string

The address's second line.

order.shipping_address.city

string

The address's city.

order.shipping_address.country_code

string

The address's country code.

Example:

"us"

order.shipping_address.province

string

The address's lower-case ISO 3166-2 province code.

Example:

"us-ca"

order.shipping_address.postal_code

string

The address's postal code.

order.shipping_address.metadata

object

The address's metadata, can hold custom key-value pairs.

order.billing_address

object

The address's details.

Show child attributes

order.billing_address.id

string

required

The address's ID.

order.billing_address.created_at

string<date-time>

required

The date the address was created.

order.billing_address.updated_at

string<date-time>

required

The date the address was updated.

order.billing_address.customer_id

string

The ID of the customer the address belongs to.

order.billing_address.first_name

string

The address's first name.

order.billing_address.last_name

string

The address's last name.

order.billing_address.phone

string

The address's phone.

order.billing_address.company

string

The address's company.

order.billing_address.address_1

string

The address's first line.

order.billing_address.address_2

string

The address's second line.

order.billing_address.city

string

The address's city.

order.billing_address.country_code

string

The address's country code.

Example:

"us"

order.billing_address.province

string

The address's lower-case ISO 3166-2 province code.

Example:

"us-ca"

order.billing_address.postal_code

string

The address's postal code.

order.billing_address.metadata

object

The address's metadata, can hold custom key-value pairs.

order.items

object[]

The order's items.

Show child attributes

order.items.id

string

required

The item's ID.

order.items.title

string

required

The item's title.

order.items.requires_shipping

boolean

required

Whether the item requires shipping.

order.items.is_discountable

boolean

required

Whether the item is discountable.

order.items.is_tax_inclusive

boolean

required

Whether the item's price includes taxes.

order.items.unit_price

number

required

The item's price for a single quantity.

order.items.quantity

number

required

The item's quantity.

order.items.detail

object

required

The order item's detail.

Show child attributes

order.items.detail.id

string

required

The item's ID.

order.items.detail.item_id

string

required

The ID of the associated line item.

order.items.detail.item

object

required

order.items.detail.quantity

number

required

The item's quantity.

order.items.detail.fulfilled_quantity

number

required

The item's fulfilled quantity.

order.items.detail.delivered_quantity

number

required

The item's delivered quantity.

order.items.detail.shipped_quantity

number

required

The item's shipped quantity.

order.items.detail.return_requested_quantity

number

required

The item's quantity that's requested to be returned.

order.items.detail.return_received_quantity

number

required

The item's quantity that's received through a return.

order.items.detail.return_dismissed_quantity

number

required

The item's quantity that's returned but dismissed because it's damaged.

order.items.detail.written_off_quantity

number

required

The item's quantity that's removed due to an order change.

order.items.detail.metadata

object

required

The item's metadata, can hold custom key-value pairs.

order.items.detail.created_at

string<date-time>

required

The date the item was created.

order.items.detail.updated_at

string<date-time>

required

The date the item was updated.

order.items.created_at

string<date-time>

required

The date the item was created.

order.items.updated_at

string<date-time>

required

The date the item was updated.

order.items.original_total

number

required

The item's total including taxes and promotions.

order.items.original_subtotal

number

required

The item's total excluding taxes, including promotions.

order.items.original_tax_total

number

required

The total taxes of the item excluding promotions.

order.items.item_total

number

required

The item's total for a single quantity, including taxes and promotions.

order.items.item_subtotal

number

required

The item's total for a single quantity, excluding taxes and including promotions.

order.items.item_tax_total

number

required

The total taxes of a single quantity of the item, including promotions.

order.items.total

number

required

The item's total including taxes and promotions.

order.items.subtotal

number

required

The item's total excluding taxes, including promotions.

order.items.tax_total

number

required

The total taxes of the item, including promotions.

order.items.discount_total

number

required

The item's discount total.

order.items.discount_tax_total

number

required

The total taxes on the discounted amount.

order.items.refundable_total

number

required

The total amount of the item that can be refunded.

order.items.refundable_total_per_unit

number

required

The total amount that can be refunded of a single quantity of the item.

order.items.is_giftcard

boolean

required

Whether the item is a gift card.

order.items.subtitle

string

The item's subtitle.

order.items.thumbnail

string

The item's thumbnail URL.

order.items.variant_id

string

The ID of the associated variant.

order.items.product_id

string

The ID of the associated product.

order.items.product_title

string

The item's product title.

order.items.product_description

string

The item's product description.

order.items.product_subtitle

string

The item's product subtitle.

order.items.product_type

string

The ID of the associated product's type.

order.items.product_collection

string

The ID of the associated product's collection.

order.items.product_handle

string

The item's product handle.

order.items.variant_sku

string

The item's variant SKU.

order.items.variant_barcode

string

The item's variant barcode.

order.items.variant_title

string

The item's variant title.

order.items.variant_option_values

object

The associated variant's values for the associated product's options.

Example:

{ "Color": "Red" }

order.items.compare_at_unit_price

number

The original price of the item before a promotion or sale.

order.items.tax_lines

object[]

The item's tax lines.

Show child attributes

order.items.tax_lines.item

object

required

order.items.tax_lines.item_id

string

required

The ID of the line item that the tax line belongs to.

order.items.tax_lines.total

number

required

The item's total including taxes and promotions.

order.items.tax_lines.subtotal

number

required

The item's total excluding taxes, including promotions.

order.items.tax_lines.id

string

required

The tax line's ID.

order.items.tax_lines.code

string

required

The code that the tax rate is identified by.

order.items.tax_lines.rate

number

required

The rate to charge.

order.items.tax_lines.created_at

string<date-time>

required

The date the tax line was created.

order.items.tax_lines.updated_at

string<date-time>

required

The date the tax line was updated.

order.items.tax_lines.description

string

The tax line's description.

order.items.tax_lines.tax_rate_id

string

The ID of the applied tax rate.

order.items.tax_lines.provider_id

string

The ID of the tax provider used to calculate the tax lines.

order.items.adjustments

object[]

The item's adjustments.

Show child attributes

order.items.adjustments.item

object

required

order.items.adjustments.item_id

string

required

The ID of the item this adjustment is for.

order.items.adjustments.id

string

required

The adjustment's ID.

order.items.adjustments.amount

number

required

The adjustment's amount.

order.items.adjustments.order_id

string

required

The ID of the associated order.

order.items.adjustments.created_at

string<date-time>

required

The date the adjustment was created.

order.items.adjustments.updated_at

string<date-time>

required

The date the adjustment was updated.

order.items.adjustments.code

string

The adjustment's code.

order.items.adjustments.description

string

The adjustment's description.

order.items.adjustments.promotion_id

string

The ID of the promotion applied by this adjustment.

order.items.adjustments.provider_id

string

The adjustment's provider ID.

order.items.metadata

object

The item's metadata, can hold custom key-value pairs.

order.items.product_type_id

string

The ID of the associated product's type.

order.shipping_methods

object[]

The order's shipping methods.

Show child attributes

order.shipping_methods.id

string

required

The shipping method's ID.

order.shipping_methods.order_id

string

required

The ID of the order that the shipping method belongs to.

order.shipping_methods.name

string

required

The shipping method's name.

order.shipping_methods.amount

number

required

The shipping method's amount.

order.shipping_methods.is_tax_inclusive

boolean

required

Whether the shipping method's amount includes taxes.

order.shipping_methods.created_at

string<date-time>

required

The date the shipping method was created.

order.shipping_methods.updated_at

string<date-time>

required

The date the shipping method was updated.

order.shipping_methods.original_total

number

required

The shipping method's total including taxes, excluding promotions.

order.shipping_methods.original_subtotal

number

required

The shipping method's subtotal excluding taxes, including promotions.

order.shipping_methods.original_tax_total

number

required

The total taxes of the shipping method excluding promotions.

order.shipping_methods.total

number

required

The shipping method's total including taxes and promotions.

order.shipping_methods.subtotal

number

required

The shipping method's total excluding taxes, including promotions.

order.shipping_methods.tax_total

number

required

The total taxes of the shipping method, including promotions.

order.shipping_methods.discount_total

number

required

The shipping method's discount total.

order.shipping_methods.discount_tax_total

number

required

The total taxes of the discount amount.

order.shipping_methods.description

string

The shipping method's description.

order.shipping_methods.shipping_option_id

string

The ID of the shipping option this method was created from.

order.shipping_methods.data

object

The shipping method's data, useful for the fulfillment provider handling the fulfillment.

order.shipping_methods.metadata

object

The shipping method's metadata, can hold custom key-value pairs.

order.shipping_methods.tax_lines

object[]

The shipping method's tax lines.

Show child attributes

order.shipping_methods.tax_lines.shipping_method

object

required

order.shipping_methods.tax_lines.shipping_method_id

string

required

The ID of the shipping method that this tax line is for.

order.shipping_methods.tax_lines.total

number

required

The shipping method's total including taxes and promotions.

order.shipping_methods.tax_lines.subtotal

number

required

The shipping method's total excluding taxes, including promotions.

order.shipping_methods.tax_lines.id

string

required

The tax line's ID.

order.shipping_methods.tax_lines.code

string

required

The code that the tax rate is identified by.

order.shipping_methods.tax_lines.rate

number

required

The rate to charge.

order.shipping_methods.tax_lines.created_at

string<date-time>

required

The date the tax line was created.

order.shipping_methods.tax_lines.updated_at

string<date-time>

required

The date the tax line was updated.

order.shipping_methods.tax_lines.description

string

The tax line's description.

order.shipping_methods.tax_lines.tax_rate_id

string

The ID of the applied tax rate.

order.shipping_methods.tax_lines.provider_id

string

The ID of the tax provider used to calculate taxes.

order.shipping_methods.adjustments

object[]

The shipping method's adjustments.

Show child attributes

order.shipping_methods.adjustments.shipping_method

object

required

order.shipping_methods.adjustments.shipping_method_id

string

required

The ID of the shipping method this adjustment is for.

order.shipping_methods.adjustments.id

string

required

The adjustment's ID.

order.shipping_methods.adjustments.amount

number

required

The adjustment's amount.

order.shipping_methods.adjustments.order_id

string

required

The ID of the associated order.

order.shipping_methods.adjustments.created_at

string<date-time>

required

The date the adjustment was created.

order.shipping_methods.adjustments.updated_at

string<date-time>

required

The date the adjustment was updated.

order.shipping_methods.adjustments.code

string

The adjustment's code.

order.shipping_methods.adjustments.description

string

The adjustment's description.

order.shipping_methods.adjustments.promotion_id

string

The ID of the promotion this adjustment applies.

order.shipping_methods.adjustments.provider_id

string

The adjustment's provider ID.

order.transactions

object[]

The order's transactions.

Show child attributes

order.transactions.id

string

required

The transaction's ID.

order.transactions.order_id

string

required

The ID of the order this transaction belongs to.

order.transactions.amount

number

required

The transaction's amount.

order.transactions.currency_code

string

required

The transaction's currency code.

Example:

"usd"

order.transactions.reference

enum<string>

required

The name of a table that this transaction references. If this transaction is for captured payment, its value is capture. If this transaction is for refunded payment, its value is refund.

Available options:

capture,

refund

order.transactions.reference_id

string

required

The ID of the referenced record in the referenced table.

order.transactions.metadata

object

required

The transaction's metadata, can hold custom key-value pairs.

order.transactions.created_at

string<date-time>

required

The date that the transaction was created.

order.transactions.updated_at

string<date-time>

required

The date that the transaction was updated.

order.transactions.order

object

required

order.transactions.version

number

required

The order version that the transaction belongs to.

order.summary

object

The order's summary.

Show child attributes

order.summary.pending_difference

number

required

The remaining amount to be paid or refunded.

order.summary.current_order_total

number

required

The order's current total.

order.summary.original_order_total

number

required

The order's total before any changes.

order.summary.transaction_total

number

required

The total of the transactions (payments and refunds) made on the order.

order.summary.paid_total

number

required

The total paid amount.

order.summary.refunded_total

number

required

The total refunded amount.

order.summary.credit_line_total

number

required

The total credit line amount.

order.summary.accounting_total

number

required

The total amount for accounting purposes.

order.summary.raw_pending_difference

object

required

The summary's raw pending difference.

order.summary.raw_current_order_total

object

required

The summary's raw current order total.

order.summary.raw_original_order_total

object

required

The summary's raw original order total.

order.summary.raw_transaction_total

object

required

The summary's raw transaction total.

order.summary.raw_paid_total

object

required

The summary's raw paid total.

order.summary.raw_refunded_total

object

required

The summary's raw refunded total.

order.summary.raw_credit_line_total

object

required

The summary's raw credit line total.

order.summary.raw_accounting_total

object

required

The summary's raw accounting total.

order.metadata

object

The order's metadata, can hold custom key-value pairs.

order.canceled_at

string<date-time>

The date the order was canceled.

order.credit_lines

object[]

The order's credit lines, useful to add additional payment amounts for an order.

Show child attributes

order.credit_lines.id

string

required

The credit line's ID.

order.credit_lines.order_id

string

required

The ID of the associated order.

order.credit_lines.order

object

required

order.credit_lines.reference

string

required

The table that this credit line references. For example, payment_collection.

order.credit_lines.reference_id

string

required

The ID of the record in the referenced table. For example, paycol_123.

order.credit_lines.metadata

object

required

The credit line's metadata, can hold custom key-value pairs.

order.credit_lines.created_at

string<date-time>

required

The date the credit line was created.

order.credit_lines.updated_at

string<date-time>

required

The date the credit line was updated.

order.credit_lines.amount

number

required

The credit line's amount.

order.is_draft_order

boolean

Whether the order is a draft order.

order.deleted_at

string<date-time>

The date the order was deleted.

order.custom_display_id

string

The custom display ID of the order.

return

object

required

The return's details.

Show child attributes

return.id

string

required

The return's ID.

return.order_id

string

required

The ID of the associated order.

return.items

object[]

required

The return's items.

Show child attributes

return.items.id

string

required

The return item's ID.

return.items.quantity

number

required

The return item's quantity.

return.items.received_quantity

number

required

The received quantity of the item. This quantity is added to the stocked inventory quantity of the item.

return.items.damaged_quantity

number

required

The received damaged quantity of the item, which isn't added to the stocked inventory quantity of the item.

return.items.item_id

string

required

The ID of the associated order item.

return.items.return_id

string

required

The ID of the return this return item belongs to.

return.items.reason_id

string

The ID of the return reason associated with the item.

return.items.note

string

A note about why the item was returned.

return.items.metadata

object

The return item's metadata, can hold custom key-value pairs.

return.created_at

string<date-time>

required

The date the return was created.

return.canceled_at

string<date-time>

required

The date the return was canceled.

return.order_version

number

required

The return's order version.

return.display_id

number

required

The return's display id.

return.received_at

string

required

The date the return was received.

return.status

enum<string>

The return's status.

Available options:

canceled,

requested,

received,

partially_received

return.refund_amount

number

The amount refunded by this return.

return.exchange_id

string

The return's exchange id.

return.location_id

string

The return's location id.

return.claim_id

string

The return's claim id.

return.no_notification

boolean

Whether the customer should receive notifications about the return's updates.

List Returns

Get a Return

⌘I

Overview

Scanner API

Admin API

Authorizations

Query Parameters

Body

Response