# Shipping

## Introduction

Through the endpoints included in the Shipping section, you will be able to:

* Calculate shipping rate for a given country and variant with specified quantity
* Retrieve information about the shipping types
* Retrieve information about the shipping methods
* Retrieve a list of countries in our system
* Retrieve a list of regions in a specific country

## Endpoints

### Shipping rates

## Calculate shipping rates

> This API endpoint retrieves a list of calculated shipping rates for the given items and shipping info

```json
{"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"schemas":{"ShippingPost":{"type":"object","properties":{"shipping":{"type":"object","required":["country"],"properties":{"country":{"type":"integer","description":"Please use /beta/countries to get country id value #/info/description"}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/ShippingItem"}}}},"ShippingItem":{"type":"object","required":["variant_id","quantity"],"properties":{"quantity":{"type":"integer"},"variant_id":{"type":"integer","description":"Please use /beta/products/{product_id} to get a certain product variant id"}}},"Error":{"type":"object","properties":{"message":{"type":"string","default":"422 Unprocessable Entity"},"errors":{"type":"object"},"status_code":{"type":"integer","default":422}}}},"responses":{"UnauthorizedError":{"description":"Unauthorized"},"LaravelError":{"description":"Unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/shipping/rates":{"post":{"summary":"Calculate shipping rates","description":"This API endpoint retrieves a list of calculated shipping rates for the given items and shipping info","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingPost"}}}},"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"price_details":{"type":"object"}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"422":{"$ref":"#/components/responses/LaravelError"}}}}}}
```

### Shipping types

## Show shipping types

> This API endpoint retrieves a list of all available shipping types

```json
{"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"}}},"paths":{"/shipping/types":{"get":{"summary":"Show shipping types","description":"This API endpoint retrieves a list of all available shipping types","responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"priority":{"type":"integer"},"code":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}}
```

### Shipping methods

## Show shipping methods

> This API endpoint retrieves a list of all available shipping methods

```json
{"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"}}},"paths":{"/shipping/methods":{"get":{"summary":"Show shipping methods","description":"This API endpoint retrieves a list of all available shipping methods","responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"An identifier for the shipping method."},"name":{"type":"string","description":"The name of the shipping method."}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}}
```

### Countries

## Show countries

> This endpoint retrieves a list of countries with IDs and their corresponding codes.

```json
{"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"}}},"paths":{"/countries":{"get":{"summary":"Show countries","description":"This endpoint retrieves a list of countries with IDs and their corresponding codes.","responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"A string representing the name of the country."},"country_id":{"type":"integer","description":"An integer representing the unique ID of the country in our system."},"country_code":{"type":"string","description":"A string representing the ISO 3166-2 code of the country."}}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}}
```

### Regions

## Show regions

> This API endpoint retrieves the list of regions within a specific country by providing its ID.

```json
{"openapi":"3.0.1","info":{"title":"merchOne API","version":"Beta"},"servers":[{"url":"https://api.merchone.com/api/beta","description":"API Beta"}],"security":[{"basicAuth":[]}],"components":{"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"}},"responses":{"UnauthorizedError":{"description":"Unauthorized"}}},"paths":{"/regions/{country_id}":{"get":{"summary":"Show regions","description":"This API endpoint retrieves the list of regions within a specific country by providing its ID.","parameters":[{"name":"country_id","in":"path","description":"ID of country from our system","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Request completed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"The unique identifier of the region in our system."},"code":{"type":"integer","description":"The region's code."},"name":{"type":"string","description":"The region's name."}}}}}}}}},"400":{"description":"Wrong argument"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}}
```

## Parameters

| Key                  | Description                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------------ |
| `shipping`           | An object that contains the country property.                                                                |
| `shipping.country`   | The ID of the country from our system, check `/api/beta/countries` for more information about the countries. |
| `items`              | An array of objects that contains information about the quantity and variant.                                |
| `items.*.quantity`   | Quantity of a variant.                                                                                       |
| `items.*.variant_id` | The ID of the variant, please check `/api/beta/products/{product_id}` for more details about the variants.   |