Developers

Shipping methods

Summary of shipping method endpoints

All endpoints except DELETE take optional query parameters that enhance the response objects:

  • include — enhance the response objects. The supported value is:
    • translations — includes translations for all translatable objects and keys.
    • cart_rules — includes all associated cart rules.
  • language_code — display all top-level values in the given language context.

List all available shipping methods for the current site

Get list of shipping methods for current site.

This endpoint also allows anonymous access.

GET /admin/api/ecommerce/v1/shipping_methods?include=translations

Example response:

Status: 200 OK

[
  {
    "id": 1,
    "name": "Basic shipping",
    "amount": "10.0",
    "description": "Basic shipping without secondary options",
    "enabled": true,
    "created_at": "2016-12-05T14:57:52.000Z",
    "updated_at": "2017-03-30T11:48:07.000Z",
    "tax_rate": null,
    "delivery_method": null,
    "options": [],
    "translations": {
      "name": {
        "en": "Basic shipping", 
        "et": "Tavatarne"
      },
      "description": {
        "en": "Basic shipping without secondary options", 
        "et": "Tavatarne ilma valikuteta"
      }
    },    
  }, {
    "id": 2,
    "name": "Advanced shipping",
    "amount": "24.0",
    "description": "Advanced shipping with multiple options",
    "enabled": true,
    "created_at": "2016-12-05T14:57:52.000Z",
    "updated_at": "2017-03-30T11:48:07.000Z",
    "tax_rate": null,
    "delivery_method": null,
    "options": [
      "option 1",
      "option 2"
    ],
    "translations": {
      "name": {
        "en": "Advanced shipping", 
        "et": "Eritarne"
      },
      "description": {
        "en": "Advanced shipping with multiple options", 
        "et": "Eritarne alamvalikutega"
      }      
    },        
  }
]

Create a new shipping method for the current site

POST /admin/api/ecommerce/v1/shipping_methods?include=translations

Example data:

{
  "name": "New shipping method",
  "amount": "15.0",
  "enabled": true,
  "delivery_method": {
    "code": "itella_pup",
    "configuration": {
      "country_code": "ee"
    }
  },
  "translations": {
    "name": {
      "en": "New shipping method", 
      "et": "Uus tarneviis"
    },
    "description": {
      "en": "Description of new shipping method", 
      "et": "Uue tarneviisi kirjeldus"
    }    
  }     
}

Example response:

Status: 201 Created

{
  "id": 3,
  "name": "New shipping method",
  "amount": "15.0",
  "description": "",
  "enabled": true,
  "created_at": "2017-03-30T11:48:07.000Z",
  "updated_at": "2017-03-30T11:48:07.000Z",
  "tax_rate": null,
  "delivery_method": {
    "code": "itella_pup",
    "configuration": {
      "country_code": "ee"
    }
  },
  "options": [
    "Elva, Elva Maxima",
    "Elva, Elva mini-Rimi",
    "Haapsalu, Haapsalu Rimi",
    "Haljala, Haljala Grossi Toidukaubad",
    "Harjumaa, Peetri Selver",
    "Imavere, Imavere Alexela",
    "Jõgeva, Jõgeva Kaubahall",
    "Jõgeva, Jõgeva Pae Konsum",
    "Jõhvi, Jõhvi Grossi Toidukaubad",
    "Jõhvi, Jõhvi Tsentraal"
  ],
  "original_options": [
    "First",
    "Second"
  ],
  "translations": {
    "name": {
      "en": "New shipping method", 
      "et": "Uus tarneviis"
    },
    "description": {
      "en": "Description of new shipping method", 
      "et": "Uue tarneviisi kirjeldus"
    }    
  }  
}

Get data for a single shipping method

GET /admin/api/ecommerce/v1/shipping_methods/1?include=translations

This endpoint also allows anonymous access.

Example request:

GET http://helloworld.voog.com/admin/api/ecommerce/v1/shipping_methods/1

Example response:

Status: 200 OK

{
  "id": 1,
  "name": "Basic shipping",
  "amount": "10.0",
  "description": "Basic shipping without secondary options",
  "enabled": true,
  "created_at": "2016-12-05T14:57:52.000Z",
  "updated_at": "2017-03-30T11:48:07.000Z",
  "tax_rate": null,
  "delivery_method": null,
  "options": [],
  "translations": {
    "name": {
      "en": "Basic shipping", 
      "et": "Tavatarne"
    },
    "description": {
      "en": "Basic shipping without secondary options", 
      "et": "Tavatarne ilma valikuteta"
    }    
  }  
}

Update attributes of a single shipping method

PUT /admin/api/ecommerce/v1/shipping_methods/1?include=translations

This request updates the shipping method with provided attributes.

Example request:

PUT http://helloworld.voog.com/admin/api/ecommerce/v1/shipping_methods/1?include=translations

Example data:

{
  "name": "Normal shipping",
  "delivery_method": {
    "code": "itella_pup",
    "configuration": {
      "country_code": "ee"
    }
  },
  "translations": {
    "name": {
      "en": "Normal shipping", 
      "et": "Tavatarne"
    },
    "description": {
      "en": "Basic shipping without secondary options", 
      "et": "Tavatarne ilma valikuteta"
    }    
  }  
}

Example response:

Status: 200 OK

{
  "id": 1,
  "name": "Normal shipping",
  "amount": "10.0",
  "description": "Basic shipping without secondary options",
  "enabled": true,
  "created_at": "2016-12-05T14:57:52.000Z",
  "updated_at": "2017-03-30T11:48:07.000Z",
  "tax_rate": null,
  "delivery_method": {
    "code": "itella_pup",
    "configuration": {
      "country_code": "ee"
    }
  },
  "options": [
    "Elva, Elva Maxima",
    "Elva, Elva mini-Rimi",
    "Haapsalu, Haapsalu Rimi",
    "Haljala, Haljala Grossi Toidukaubad",
    "Harjumaa, Peetri Selver",
    "Imavere, Imavere Alexela",
    "Jõgeva, Jõgeva Kaubahall",
    "Jõgeva, Jõgeva Pae Konsum",
    "Jõhvi, Jõhvi Grossi Toidukaubad",
    "Jõhvi, Jõhvi Tsentraal"
  ],  
  "original_options": [
    "First",
    "Second"
  ],  
  "translations": {
    "name": {
      "en": "Normal shipping", 
      "et": "Tavatarne"
    },
    "description": {
      "en": "Basic shipping without secondary options", 
      "et": "Tavatarne ilma valikuteta"
    }    
  }  
}

Parameters

  • name — Shipping method name as it appears in the shopping cart dropdown
  • description — A descriptive text that is shown in the shopping cart after selecting the method
  • delivery_method — An object configuring a preset physical delivery method for the shipping method. Parameters:
    • code — Delivery method code. Currently supported: itella_pup (Itella pick-up points), omniva_pup (Omniva pick-up points), dpd_pup (DPD pick-up points).
    • configuration — An object configuring the selected delivery method. Currently the only supported configuration key is country_code. The allowed values by delivery method are:
    • itella_pup: ee, fi
    • omniva_pup: ee, lv, lt
    • dpd_pup: ee, lv, lt
  • options — List of strings that are used as sub-options for the method, e.g. possible pickup locations. Void if delivery_method is passed; in such case the options array is populated automatically by the delivery method and the original options are returned via original_options.
  • amount — The subtotal amount of the given method
  • tax_rate — The tax rate that is used for the method's total price calculation (defaults to Store's tax_rate if not specified)
  • enabled — A boolean that controls whether the method is rendered in the cart or not

Remove a shipping method

DELETE /admin/api/ecommerce/v1/shipping_methods/1

This request deletes the given shipping method.

Example request:

DELETE http://helloworld.voog.com/admin/api/ecommerce/v1/shipping_methods/1

Example response:

Status: 204 No Content