Medusa

List Swaps

GET

/admin/swaps

Swaps

Retrieve a list of Swaps. The swaps can be paginated.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'https://api.medusa-commerce.com/admin/swaps'

Response Example

200 - Example 1

{
  "count": 0,
  "offset": 0,
  "limit": 0,
  "swaps": [
    {
      "id": "swap_01F0YET86Y9G92D3YDR9Y6V676",
      "order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
      "order": {},
      "return_order": {},
      "payment": {},
      "difference_due": 0,
      "shipping_address_id": "addr_01G8ZH853YPY9B94857DY91YGW",
      "cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
      "cart": {},
      "confirmed_at": "2019-08-24T14:15:22Z",
      "canceled_at": "2019-08-24T14:15:22Z",
      "no_notification": false,
      "allow_backorder": false,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "deleted_at": "2019-08-24T14:15:22Z",
      "fulfillment_status": "not_fulfilled",
      "payment_status": "not_paid",
      "fulfillments": [
        {}
      ],
      "idempotency_key": "string",
      "metadata": {
        "car": "white"
      },
      "shipping_address": {
        "id": "addr_01G8ZC9VS1XVE149MGH2J7QSSH",
        "customer_id": "cus_01G2SG30J8C85S4A5CHM2S1NS2",
        "customer": {},
        "company": "Acme",
        "first_name": "Arno",
        "last_name": "Willms",
        "address_1": "14433 Kemmer Court",
        "address_2": "Suite 369",
        "city": "South Geoffreyview",
        "province": "Kentucky",
        "postal_code": 72093,
        "phone": 16128234334802,
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "deleted_at": "2019-08-24T14:15:22Z",
        "country_code": "st",
        "metadata": {
          "car": "white"
        },
        "country": {
          "id": 109,
          "name": "ITALY",
          "display_name": "Italy",
          "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
          "region": {},
          "iso_2": "it",
          "iso_3": "ita",
          "num_code": 380
        }
      },
      "shipping_methods": [
        {
          "id": "sm_01F0YET7DR2E7CYVSDHM593QG2",
          "shipping_option_id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
          "order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
          "order": {},
          "claim_order_id": null,
          "claim_order": {},
          "cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
          "cart": {},
          "swap_id": null,
          "swap": {},
          "return_id": null,
          "return_order": {},
          "price": 200,
          "includes_tax": false,
          "subtotal": 8000,
          "total": 8200,
          "tax_total": 0,
          "data": {},
          "tax_lines": [
            {
              "id": "smtl_01G1G5V2DRX1SK6NQQ8VVX4HQ8",
              "code": "tax01",
              "name": "Tax Example",
              "rate": 10,
              "shipping_method_id": "sm_01F0YET7DR2E7CYVSDHM593QG2",
              "shipping_method": {},
              "created_at": "2019-08-24T14:15:22Z",
              "updated_at": "2019-08-24T14:15:22Z",
              "metadata": {
                "car": "white"
              }
            }
          ],
          "shipping_option": {
            "id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
            "name": "PostFake Standard",
            "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
            "region": {},
            "profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
            "provider_id": "manual",
            "amount": 200,
            "is_return": false,
            "admin_only": false,
            "includes_tax": false,
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "deleted_at": "2019-08-24T14:15:22Z",
            "price_type": "flat_rate",
            "data": {},
            "metadata": {
              "car": "white"
            },
            "provider": {
              "id": "manual",
              "is_installed": true
            },
            "requirements": [
              {
                "id": "sor_01G1G5V29AB4CTNDRFSRWSRKWD",
                "shipping_option_id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
                "shipping_option": {},
                "amount": 100,
                "deleted_at": "2019-08-24T14:15:22Z",
                "type": "min_subtotal"
              }
            ],
            "profile": {
              "id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
              "name": "Default Shipping Profile",
              "created_at": "2019-08-24T14:15:22Z",
              "updated_at": "2019-08-24T14:15:22Z",
              "deleted_at": "2019-08-24T14:15:22Z",
              "type": "default",
              "products": [
                {}
              ],
              "shipping_options": [
                {}
              ],
              "metadata": {
                "car": "white"
              }
            }
          }
        }
      ],
      "additional_items": [
        {
          "id": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN",
          "cart_id": "cart_01G8ZH853Y6TFXWPG5EYE81X63",
          "cart": {},
          "order_id": "order_01G8TJSYT9M6AVS5N4EMNFS1EK",
          "order": {},
          "swap_id": null,
          "swap": {},
          "claim_order_id": null,
          "claim_order": {},
          "original_item_id": "string",
          "order_edit_id": "string",
          "order_edit": {},
          "title": "Medusa Coffee Mug",
          "description": "One Size",
          "thumbnail": "https://medusa-public-images.s3.eu-west-1.amazonaws.com/coffee-mug.png",
          "is_return": false,
          "is_giftcard": false,
          "should_merge": true,
          "allow_discounts": true,
          "has_shipping": false,
          "unit_price": 8000,
          "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
          "quantity": 1,
          "fulfilled_quantity": 0,
          "returned_quantity": 0,
          "shipped_quantity": 0,
          "refundable": 0,
          "subtotal": 8000,
          "tax_total": 0,
          "total": 8000,
          "original_total": 8000,
          "original_tax_total": 0,
          "discount_total": 0,
          "raw_discount_total": 0,
          "gift_card_total": 0,
          "includes_tax": false,
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "metadata": {
            "car": "white"
          },
          "tax_lines": [
            {
              "id": "litl_01G1G5V2DRX1SK6NQQ8VVX4HQ8",
              "code": "tax01",
              "name": "Tax Example",
              "rate": 10,
              "item_id": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN",
              "item": {},
              "created_at": "2019-08-24T14:15:22Z",
              "updated_at": "2019-08-24T14:15:22Z",
              "metadata": {
                "car": "white"
              }
            }
          ],
          "variant": {
            "id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
            "title": "Small",
            "product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
            "product": {},
            "sku": "shirt-123",
            "barcode": null,
            "ean": null,
            "upc": null,
            "variant_rank": 0,
            "inventory_quantity": 100,
            "allow_backorder": false,
            "manage_inventory": true,
            "hs_code": null,
            "origin_country": null,
            "mid_code": null,
            "material": null,
            "weight": null,
            "length": null,
            "height": null,
            "width": null,
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "deleted_at": "2019-08-24T14:15:22Z",
            "purchasable": true,
            "metadata": {
              "car": "white"
            },
            "options": [
              {
                "id": "optval_01F0YESHR7S6ECD03RF6W12DSJ",
                "value": "large",
                "option_id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
                "option": {},
                "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
                "variant": {},
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "deleted_at": "2019-08-24T14:15:22Z",
                "metadata": {
                  "car": "white"
                }
              }
            ],
            "inventory_items": [
              {
                "id": "pvitem_01G8X9A7ESKAJXG2H0E6F1MW7A",
                "inventory_item_id": "string",
                "variant_id": "string",
                "variant": {},
                "required_quantity": 1,
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "deleted_at": "2019-08-24T14:15:22Z"
              }
            ],
            "prices": [
              {
                "id": "ma_01F0YESHRFQNH5S8Q0PK84YYZN",
                "amount": 100,
                "min_quantity": 1,
                "max_quantity": 1,
                "price_list_id": "pl_01G8X3CKJXCG5VXVZ87H9KC09W",
                "price_list": {},
                "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
                "variant": {},
                "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                "region": {},
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "deleted_at": "2019-08-24T14:15:22Z",
                "currency_code": "usd",
                "currency": {
                  "symbol": "$",
                  "symbol_native": "$",
                  "name": "US Dollar",
                  "includes_tax": false,
                  "code": "usd"
                }
              }
            ]
          },
          "adjustments": [
            {
              "id": "lia_01G8TKE4XYCTHSCK2GDEP47RE1",
              "item_id": "item_01G8ZC9GWT6B2GP5FSXRXNFNGN",
              "item": {},
              "description": "Adjusted item's price.",
              "discount_id": "disc_01F0YESMW10MGHWJKZSDDMN0VN",
              "amount": 1000,
              "metadata": {
                "car": "white"
              },
              "discount": {
                "id": "disc_01F0YESMW10MGHWJKZSDDMN0VN",
                "code": "10DISC",
                "is_dynamic": false,
                "rule_id": "dru_01F0YESMVK96HVX7N419E3CJ7C",
                "is_disabled": false,
                "parent_discount_id": "disc_01G8ZH853YPY9B94857DY91YGW",
                "parent_discount": {},
                "starts_at": "2019-08-24T14:15:22Z",
                "ends_at": "2019-08-24T14:15:22Z",
                "valid_duration": "P3Y6M4DT12H30M5S",
                "usage_limit": 100,
                "usage_count": 0,
                "created_at": "2019-08-24T14:15:22Z",
                "updated_at": "2019-08-24T14:15:22Z",
                "deleted_at": "2019-08-24T14:15:22Z",
                "metadata": {
                  "car": "white"
                },
                "rule": {
                  "id": "dru_01F0YESMVK96HVX7N419E3CJ7C",
                  "description": "10 Percent",
                  "value": 10,
                  "created_at": "2019-08-24T14:15:22Z",
                  "updated_at": "2019-08-24T14:15:22Z",
                  "deleted_at": "2019-08-24T14:15:22Z",
                  "type": "fixed",
                  "allocation": "total",
                  "conditions": [
                    {}
                  ],
                  "metadata": {
                    "car": "white"
                  }
                },
                "regions": [
                  {
                    "id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                    "name": "EU",
                    "tax_rate": 0,
                    "tax_code": null,
                    "gift_cards_taxable": true,
                    "automatic_taxes": true,
                    "tax_provider_id": null,
                    "includes_tax": false,
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z",
                    "currency_code": "usd",
                    "metadata": {
                      "car": "white"
                    },
                    "currency": {
                      "symbol": "$",
                      "symbol_native": "$",
                      "name": "US Dollar",
                      "includes_tax": false,
                      "code": "usd"
                    },
                    "countries": [
                      {
                        "id": 109,
                        "name": "ITALY",
                        "display_name": "Italy",
                        "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                        "region": {},
                        "iso_2": "it",
                        "iso_3": "ita",
                        "num_code": 380
                      }
                    ],
                    "tax_provider": {
                      "id": "manual",
                      "is_installed": true
                    },
                    "payment_providers": [
                      {
                        "id": "manual",
                        "is_installed": true
                      }
                    ],
                    "fulfillment_providers": [
                      {
                        "id": "manual",
                        "is_installed": true
                      }
                    ],
                    "tax_rates": [
                      {
                        "id": "txr_01G8XDBAWKBHHJRKH0AV02KXBR",
                        "rate": 10,
                        "code": "tax01",
                        "name": "Tax Example",
                        "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                        "region": {},
                        "product_count": 10,
                        "product_type_count": 2,
                        "shipping_option_count": 1,
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "metadata": {
                          "car": "white"
                        },
                        "product_types": [
                          {
                            "id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
                            "value": "Clothing",
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "metadata": {
                              "car": "white"
                            }
                          }
                        ],
                        "shipping_options": [
                          {
                            "id": "so_01G1G5V27GYX4QXNARRQCW1N8T",
                            "name": "PostFake Standard",
                            "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
                            "region": {},
                            "profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                            "provider_id": "manual",
                            "amount": 200,
                            "is_return": false,
                            "admin_only": false,
                            "includes_tax": false,
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "price_type": "flat_rate",
                            "data": {},
                            "metadata": {
                              "car": "white"
                            },
                            "provider": {},
                            "requirements": [
                              null
                            ],
                            "profile": {
                              "products": [],
                              "shipping_options": [],
                              "metadata": {}
                            }
                          }
                        ],
                        "products": [
                          {
                            "id": "prod_01G1G5V2MBA328390B5AXJ610F",
                            "title": "Medusa Coffee Mug",
                            "subtitle": "string",
                            "description": "Every programmer's best friend.",
                            "handle": "coffee-mug",
                            "is_giftcard": false,
                            "thumbnail": "http://example.com",
                            "profile_id": "sp_01G1G5V239ENSZ5MV4JAR737BM",
                            "weight": null,
                            "length": null,
                            "height": null,
                            "width": null,
                            "hs_code": null,
                            "origin_country": null,
                            "mid_code": null,
                            "material": null,
                            "collection_id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
                            "type_id": "ptyp_01G8X9A7ESKAJXG2H0E6F1MW7A",
                            "discountable": true,
                            "external_id": null,
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "status": "draft",
                            "metadata": {
                              "car": "white"
                            },
                            "images": [
                              null
                            ],
                            "categories": [
                              null
                            ],
                            "collection": {
                              "products": [],
                              "metadata": {}
                            },
                            "tags": [
                              null
                            ],
                            "profile": {
                              "products": [],
                              "shipping_options": [],
                              "metadata": {}
                            },
                            "profiles": [
                              null
                            ],
                            "type": {
                              "metadata": {}
                            },
                            "sales_channels": [
                              null
                            ],
                            "options": [
                              null
                            ],
                            "variants": [
                              null
                            ]
                          }
                        ]
                      }
                    ]
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

Request

Query Params

limit

number

optional

Limit the number of swaps returned.

offset

number

optional

The number of swaps to skip when retrieving the swaps.

Responses

🟢200OK

application/json

Body

count

integer

required

The total number of items available

offset

integer

required

The number of swaps skipped when retrieving the swaps.

limit

integer

required

The number of items per page

swaps

array[object (Swap) {24}]

required

An array of swaps details.

string

required

The swap's ID

Example:

swap_01F0YET86Y9G92D3YDR9Y6V676

order_id

string

required

The ID of the order that the swap belongs to.

Example:

order_01G8TJSYT9M6AVS5N4EMNFS1EK

order

object | null

optional

The details of the order that the swap belongs to.

return_order

object | null

optional

The details of the return that belongs to the swap, which holds the details on the items being returned.

payment

object | null

optional

The details of the additional payment authorized by the customer when difference_due is positive.

difference_due

integer | null

required

The difference amount between the order’s original total and the new total imposed by the swap. If its value is negative, a refund must be issues to the customer. If it's positive, additional payment must be authorized by the customer. Otherwise, no payment processing is required.

Example:

shipping_address_id

string | null

required

The Address to send the new Line Items to - in most cases this will be the same as the shipping address on the Order.

Example:

addr_01G8ZH853YPY9B94857DY91YGW

cart_id

string | null

required

The ID of the cart that the customer uses to complete the swap.

Example:

cart_01G8ZH853Y6TFXWPG5EYE81X63

cart

object | null

optional

The details of the cart that the customer uses to complete the swap.

confirmed_at

string <date-time> | null

required

The date with timezone at which the Swap was confirmed by the Customer.

canceled_at

string <date-time> | null

required

The date with timezone at which the Swap was canceled.

no_notification

boolean | null

required

If set to true, no notification will be sent related to this swap

Example:

false

allow_backorder

boolean

required

If true, swaps can be completed with items out of stock

Default:

false

created_at

string <date-time>

required

The date with timezone at which the resource was created.

updated_at

string <date-time>

required

The date with timezone at which the resource was updated.

deleted_at

string <date-time> | null

required

The date with timezone at which the resource was deleted.

fulfillment_status

enum<string>

required

The status of the Fulfillment of the Swap.

Allowed values:

not_fulfilledfulfilledshippedpartially_shippedcanceledrequires_action

Example:

not_fulfilled

payment_status

enum<string>

required

The status of the Payment of the Swap. The payment may either refer to the refund of an amount or the authorization of a new amount.

Allowed values:

not_paidawaitingcapturedconfirmedcanceleddifference_refundedpartially_refundedrefundedrequires_action

Example:

not_paid

fulfillments

array [object]

optional

The details of the fulfillments that are used to send the new items to the customer.

idempotency_key

string | null

required

Randomly generated key used to continue the completion of the swap in case of failure.

metadata

object | null

required

An optional key-value map with additional details

Example:

{"car":"white"}

shipping_address

object (Address)

optional

An address is used across the Medusa backend within other schemas and object types. For example, a customer's billing and shipping addresses both use the Address entity.

shipping_methods

array[object (Shipping Method) {20}]

optional

The details of the shipping methods used to fulfill the additional items purchased.

additional_items

array[object (Line Item) {42}]

optional

The details of the new products to send to the customer, represented as line items.

🟠400Client Error or Multiple Errors

🟠401User is not authorized. Must log in first

🟠404Not Found Error

🟠409Invalid State Error

🟠422Invalid Request Error

🔴500Server Error

Modified at 2023-10-10 11:56:36

Get a Swap

Upload Files