Menu

Regions API Routes

Regions are different countries or geographical regions that the commerce store serves customers in.

These API routes allow admin users to manage regions, their providers, and more.

GET /admin/regions#

List Regions

Retrieve a list of regions. The regions can be filtered by fields such as id. The regions can also be sorted or paginated.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
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.
offsetnumberOptional
The number of items to skip when retrieving a list.
limitnumberOptional
Limit the number of items returned in the list.
orderstringOptional
The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.
qstringOptional
Search term to filter the region's searchable properties.
idstring | string[]Optional
Filter by a region's ID.
namestring | string[]Optional
Filter by a region's name.
created_atobjectOptional
Filter by a region's creation date. Accepts the filter operators.
updated_atobjectOptional
Filter by a region's update date. Accepts the filter operators.
deleted_atobjectOptional
Filter by a region's deletion date. Accepts the filter operators.
$andobject[]Optional
Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
$orobject[]Optional
Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
currency_codestring | string[]Optional
The region's currency code.
with_deletedbooleanOptional
Whether to include deleted records in the result.

Request examples

Responses

200 OK

limitnumber
The maximum number of items returned.
offsetnumber
The number of items skipped before retrieving the returned items.
countnumber
The total number of items.
regionsobject[]
The list of regions.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/regions#

Create Region

Create a region.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Query parameters

fieldsstringOptional
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.

Request body (application/json)

namestring
The region's name.
currency_codestring
The region's currency code.
Example: usd
countriesstring[]Optional
The region's countries.
automatic_taxesbooleanOptional
Whether taxes are calculated automatically during checkout in this region.
is_tax_inclusivebooleanOptional
Whether prices in this region are tax inclusive.
payment_providersstring[]Optional
The payment providers enabled in this region.
metadataobjectOptional
The region's metadata, used to store custom key-value pairs. Learn more in the Manage Metadata section.

Request examples

Responses

200 OK

regionobject
The region's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • region.created: Emitted when regions are created.

GET /admin/regions/{id}#

Get a Region

Retrieve a region by its ID. You can expand the region's relations or select the fields that should be returned.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The region's ID.

Query parameters

fieldsstringOptional
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.

Request examples

Responses

200 OK

regionobject
The region's details.

400, 401, 404, 409, 422, 500: an error response is returned.

POST /admin/regions/{id}#

Update a Region

Update a region's details.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The region's ID.

Query parameters

fieldsstringOptional
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.

Request body (application/json)

namestringOptional
The region's name.
currency_codestringOptional
The region's currency code.
countriesstring[]Optional
The region's countries.
automatic_taxesbooleanOptional
Whether taxes are calculated automatically for carts in the region.
payment_providersstring[]Optional
The payment providers enabled in the region.
metadataobjectOptional
The region's metadata. Can hold custom key-value pairs. Learn more in the Manage Metadata section.
is_tax_inclusivebooleanOptional
Whether the prices in the region are tax inclusive.

Request examples

Responses

200 OK

regionobject
The region's details.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • region.updated: Emitted when regions are updated.

DELETE /admin/regions/{id}#

Delete a Region

Delete a region.

Authentication: secret API key (HTTP Basic authorization), cookie session, JWT bearer token.

Path parameters

idstring
The region's ID.

Request examples

Responses

200 OK

idstring
The region's ID.
objectstring
The name of the deleted object.

Default: "region"

deletedboolean
Whether the region was deleted.

400, 401, 404, 409, 422, 500: an error response is returned.

Emitted events

  • region.deleted: Emitted when regions are deleted.
Found a problem with this page?Report Issue
Edited Nov 14·Edit this page