List Regions

Retrieve a list of Regions. The regions can be filtered by fields such as created_at. The regions can also be paginated

Request

Query Params

limit

integer

optional

Limit the number of regions returned.

offset

integer

optional

The number of regions to skip when retrieving the regions.

array[string]

optional

filter by dates less than this date

Example:

["","",""]

array[string]

optional

filter by dates greater than this date

Example:

["","",""]

lte

array[string]

optional

filter by dates less than or equal to this date

Example:

["","",""]

gte

array[string]

optional

filter by dates greater than or equal to this date

Example:

["","",""]

Responses

🟢200OK

application/json

Body

count

integer

required

The total number of items available

offset

integer

required

The number of regions skipped when retrieving the regions.

limit

integer

required

The number of items per page

regions

array[object (Region) {19}]

required

An array of regions details.

string

required

The region's ID

Example:

reg_01G1G5V26T9H8Y0M4JNE3YGA4G

name

string

required

The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.

Example:

tax_rate

number

required

The tax rate that should be charged on purchases in the Region.

Example:

tax_code

string | null

required

The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.

Example:

null

gift_cards_taxable

boolean

required

Whether the gift cards are taxable or not in this region.

Default:

true

automatic_taxes

boolean

required

Whether taxes should be automated in this region.

Default:

true

tax_provider_id

string | null

required

The ID of the tax provider used in this region

Example:

null

includes_tax

boolean

optional

Whether the prices for the region include tax

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.

currency_code

string

required

The 3 character currency code used in the region.

Example:

usd

metadata

object | null

required

An optional key-value map with additional details

Example:

{"car":"white"}

currency

object (Currency)

optional

Currency

countries

array[object (Country) {8}]

optional

The details of the countries included in this region.

tax_provider

object (Tax Provider)

optional

A tax provider represents a tax service installed in the Medusa backend, either through a plugin or backend customizations. It holds the tax service's installation status.

payment_providers

array[object (Payment Provider) {2}]

optional

The details of the payment providers that can be used to process payments in the region.

fulfillment_providers

array[object (Fulfillment Provider) {2}]

optional

The details of the fulfillment providers that can be used to fulfill items of orders and similar resources in the region.

tax_rates

array[object (Tax Rate) {15}]

optional

The details of the tax rates used in the region, aside from the default rate.

Example

{
  "count": 0,
  "offset": 0,
  "limit": 0,
  "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": {
                "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"
                }
              }
            }
          ],
          "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": [
                {
                  "id": "img_01G749BFYR6T8JTVW6SGW3K3E6",
                  "url": "http://example.com",
                  "created_at": "2019-08-24T14:15:22Z",
                  "updated_at": "2019-08-24T14:15:22Z",
                  "deleted_at": "2019-08-24T14:15:22Z",
                  "metadata": {
                    "car": "white"
                  }
                }
              ],
              "categories": [
                {
                  "id": "pcat_01G2SG30J8C85S4A5CHM2S1NS2",
                  "name": "Regular Fit",
                  "handle": "regular-fit",
                  "mpath": "pcat_id1.pcat_id2.pcat_id3",
                  "is_internal": false,
                  "is_active": false,
                  "rank": 0,
                  "parent_category_id": null,
                  "parent_category": {},
                  "created_at": "2019-08-24T14:15:22Z",
                  "updated_at": "2019-08-24T14:15:22Z",
                  "category_children": [
                    {}
                  ],
                  "products": [
                    {}
                  ]
                }
              ],
              "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"
                }
              },
              "tags": [
                {
                  "id": "ptag_01G8K2MTMG9168F2B70S1TAVK3",
                  "value": "Pants",
                  "created_at": "2019-08-24T14:15:22Z",
                  "updated_at": "2019-08-24T14:15:22Z",
                  "deleted_at": "2019-08-24T14:15:22Z",
                  "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"
                }
              },
              "profiles": [
                {
                  "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"
                  }
                }
              ],
              "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"
                }
              },
              "sales_channels": [
                {
                  "id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
                  "name": "Market",
                  "description": "Multi-vendor market",
                  "is_disabled": false,
                  "created_at": "2019-08-24T14:15:22Z",
                  "updated_at": "2019-08-24T14:15:22Z",
                  "deleted_at": "2019-08-24T14:15:22Z",
                  "metadata": {
                    "car": "white"
                  },
                  "locations": [
                    {
                      "id": "scloc_01G8X9A7ESKAJXG2H0E6F1MW7A",
                      "sales_channel_id": "sc_01G8X9A7ESKAJXG2H0E6F1MW7A",
                      "location_id": "string",
                      "sales_channel": {},
                      "created_at": "2019-08-24T14:15:22Z",
                      "updated_at": "2019-08-24T14:15:22Z",
                      "deleted_at": "2019-08-24T14:15:22Z"
                    }
                  ]
                }
              ],
              "options": [
                {
                  "id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
                  "title": "Size",
                  "product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
                  "product": {},
                  "created_at": "2019-08-24T14:15:22Z",
                  "updated_at": "2019-08-24T14:15:22Z",
                  "deleted_at": "2019-08-24T14:15:22Z",
                  "metadata": {
                    "car": "white"
                  },
                  "values": [
                    {
                      "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"
                      }
                    }
                  ]
                }
              ],
              "variants": [
                {
                  "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"
                      }
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

🟠400Client Error or Multiple Errors

🟠401User is not authorized. Must log in first

🟠404Not Found Error

🟠409Invalid State Error

🟠422Invalid Request Error

🔴500Server Error

Request

Request samples

Responses