Create a Swap - Medusa

Create a Swap for an Order. This will also create a return and associate it with the swap. If a return shipping option is specified, the return will automatically be fulfilled.
To complete the swap, you must use the Complete Cart API Route passing it the ID of the swap's cart.

An idempotency key will be generated if none is provided in the header Idempotency-Key and added to
the response. If an error occurs during swap creation or the request is interrupted for any reason, the swap creation can be retried by passing the idempotency
key in the Idempotency-Key header.

Request

Body Params application/json

order_id

string

required

The ID of the Order to create the Swap for.

return_shipping_option

string

optional

The ID of the Shipping Option to create the Shipping Method from.

additional_items

array [object {2}]

required

The items to exchange the returned items with.

variant_id

string

required

The ID of the Product Variant.

quantity

integer

required

The quantity of the variant.

return_items

array [object {4}]

required

The items to include in the Return.

item_id

string

required

The ID of the order's line item to return.

quantity

integer

required

The quantity to return.

reason_id

string

optional

The ID of the reason of this return. Return reasons can be retrieved from the List Return Reasons API Route.

note

string

optional

The note to add to the item being swapped.

Example

{
  "order_id": "string",
  "return_shipping_option": "string",
  "additional_items": [
    {
      "variant_id": "string",
      "quantity": 0
    }
  ],
  "return_items": [
    {
      "item_id": "string",
      "quantity": 0,
      "reason_id": "string",
      "note": "string"
    }
  ]
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Body

The swap's details.

swap

object (Swap)

required

A swap can be created when a Customer wishes to exchange Products that they have purchased with different Products. It consists of a Return of previously purchased Products and a Fulfillment of new Products. It also includes information on any additional payment or refund required based on the difference between the exchanged products.

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.

Example

{
  "swap": {
    "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"
          },
          "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"
            }
          },
          "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"
            }
          ]
        }
      }
    ],
    "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"
                          },
                          "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"
                            }
                          },
                          "provider": {
                            "id": "manual",
                            "is_installed": true
                          },
                          "requirements": [
                            {
                              "shipping_option": {}
                            }
                          ]
                        }
                      ],
                      "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"
                          },
                          "categories": [
                            {
                              "parent_category": {},
                              "category_children": [],
                              "products": [],
                              "metadata": {}
                            }
                          ],
                          "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"
                            }
                          },
                          "profiles": [
                            {
                              "products": [],
                              "shipping_options": [],
                              "metadata": {}
                            }
                          ],
                          "collection": {
                            "id": "pcol_01F0YESBFAZ0DV6V831JXWH0BG",
                            "title": "Summer Collection",
                            "handle": "summer-collection",
                            "created_at": "2019-08-24T14:15:22Z",
                            "updated_at": "2019-08-24T14:15:22Z",
                            "deleted_at": "2019-08-24T14:15:22Z",
                            "products": [
                              {}
                            ],
                            "metadata": {
                              "car": "white"
                            }
                          },
                          "type": {
                            "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"
                            }
                          },
                          "tags": [
                            {
                              "metadata": {}
                            }
                          ],
                          "images": [
                            {
                              "metadata": {}
                            }
                          ],
                          "options": [
                            {
                              "product": {},
                              "metadata": {},
                              "values": []
                            }
                          ],
                          "sales_channels": [
                            {
                              "metadata": {},
                              "locations": []
                            }
                          ],
                          "variants": [
                            {
                              "product": {},
                              "metadata": {},
                              "options": [],
                              "inventory_items": [],
                              "prices": []
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

🟠400Client Error or Multiple Errors

🟠404Not Found Error

🟠409Invalid State Error

🟠422Invalid Request Error

🔴500Server Error