Medusa
Store APIAdmin API
Store APIAdmin API
Discord
Twitter
Linkedin
Github
  1. Regions
  • Getting Started
    • Introduction
    • Authentication
    • HTTP Compression
    • Publishable API Key
    • Expanding Fields
    • Selecting Fields
    • Query Parameter Types
    • Pagination
  • Auth
    • Customer Login (JWT)
      POST
    • Customer Login (JWT)
      POST
    • Check if Email Exists
      GET
    • Get Current Customer
      GET
    • Customer Log out
      DELETE
    • Customer Login
      POST
  • Carts
    • Create Payment Sessions
      POST
    • Refresh a Payment Session
      POST
    • Create a Cart
      POST
    • Complete a Cart
      POST
    • Select a Payment Session
      POST
    • Delete a Payment Session
      DELETE
    • Update a Payment Session
      POST
    • Get a Cart
      GET
    • Update a Cart
      POST
    • Add Shipping Method
      POST
    • Update a Line Item
      POST
    • Delete a Line Item
      DELETE
    • Add a Line Item
      POST
    • Calculate Cart Taxes
      POST
    • Remove Discount
      DELETE
  • Customers
    • Request Password Reset
    • Get Saved Payment Methods
    • Add a Shipping Address
    • Update Customer
    • Get a Customer
    • Update a Shipping Address
    • Delete an Address
    • Create a Customer
    • Reset Password
    • List Orders
  • Gift Cards
    • Get Gift Card by Code
  • Orders
    • Claim Order
    • Verify Order Claim
    • Get an Order
    • Look Up an Order
    • Get by Cart ID
  • Order Edits
    • Complete an Order Edit
    • Retrieve an Order Edit
    • Decline an Order Edit
  • Payment Collections
    • Authorize Payment Session
    • Authorize Payment Sessions
    • Refresh a Payment Session
    • Get a PaymentCollection
    • Manage Payment Sessions
    • Create a Payment Session
  • Products
    • Search Products
    • List Products
    • Get a Product
  • Product Variants
    • Get a Product Variant
    • Get Product Variants
  • Product Tags
    • List Product Tags
  • Product Categories
    • List Product Categories
    • Get a Product Category
  • Product Collections
    • Get a Collection
    • List Collections
  • Product Types
    • List Product Types
  • Regions
    • List Regions
      GET
    • Get a Region
      GET
  • Returns
    • Create Return
  • Return Reasons
    • List Return Reasons
    • Get a Return Reason
  • Shipping Options
    • List for Cart
    • Get Shipping Options
  • Swaps
    • Get by Cart ID
    • Create a Swap
  1. Regions

List Regions

GET
/store/regions
Regions
Retrieve a list of regions. The regions can be filtered by fields such as created_at. The regions can also be paginated. This API Route is useful to show the customer all available regions to choose from.
Request Request Example
Shell
JavaScript
Java
Swift
curl --location -g --request GET '{{BASE_URL}}/store/regions'
Response Response Example
200 - Example 1
{
  "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"
              },
              "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"
                }
              ]
            }
          ],
          "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": [
                {
                  "id": "pcat_01G2SG30J8C85S4A5CHM2S1NS2",
                  "name": "Regular Fit",
                  "description": "",
                  "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": [
                    {}
                  ],
                  "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"
                  }
                }
              ],
              "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": [
                {
                  "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"
                  }
                }
              ],
              "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"
                  }
                }
              ],
              "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"
                      }
                    }
                  ]
                }
              ],
              "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"
                    }
                  ]
                }
              ],
              "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"
                      }
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Request

Query Params
offset
integer 
optional
The number of regions to skip when retrieving the regions.
limit
integer 
optional
Limit the number of regions returned.
lt
array[string]
optional
filter by dates less than this date
Example:
["",""]
gt
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
The list of regions with pagination fields.
count
integer 
optional
The total number of items available
offset
integer 
optional
The number of regions skipped when retrieving the regions.
limit
integer 
optional
The number of items per page
regions
array[object (Region) {19}] 
required
An array of regions details.
id
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:
EU
tax_rate
number 
required
The tax rate that should be charged on purchases in the Region.
Example:
0
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 three 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.
🟠400Client Error or Multiple Errors
🟠404Not Found Error
🟠409Invalid State Error
🟠422Invalid Request Error
🔴500Server Error
Modified at 2023-11-27 13:05:07
Previous
List Product Types
Next
Get a Region
Built with