SEOshop Documentation

Ik# Create a shipping integration
You can now create your own shipment service and integrate this easily with our checkout. During the checkout process, we will call your API to fetch the available methods. No custom javascript or css needed!

See this example, where the app MyAwesomeApp displays pick up locations close to the customer, dynamically.

It is recommended that you inform the merchant about the use of personal data. The privacy policy should reflect the use of personal data.

Shipping methods

Introduction

You'll start off by creating an ExternalService through the API. A External service can either be a payment or a shipping integration. Send a POST request to the /external_services endpoint with the details of your service. Please note that the urlEndpoint will be the url that we'll make requests to, and this must be over HTTPS.

Some general tips:

  1. You can fetch all your current external_services after creation;
  2. If your service already exist, you can make a PUT call to change the current external service;
  3. You can delete current external services with a DELETE call: Webshop::instance()->external_services->delete(ID)

Now start a new checkout and go to the shipment methods step. Notice that we call your {urlEndpoint}/shipment_methods to fetch the available methods. See the Fetching payment methods chapter.

If you set rateEstimate to true, we'll also call your service in the cart to fetch the rates. This call differs in the payload, as we do not yet have that much customer information in the cart yet.

Arguments

NameValue
type

The type of external service, for example a payment service integration.

{"type": "shipment|payment"}
name

The name of the service. This will be shown to customers in the checkout process.

{"name": "SEOshop Payments"}
urlEndpoint

The url to your endpoint that we'll send requests to. For example we'll send a POST request to {urlEndpoint}/payment_methods. Please note that HTTPS is required.

{"urlEndpoint": "https://api.yourdomain.com/"}
isActive

Enable or disable the external service
(format: boolean)

{"isActive": "true|false"}
rateEstimate

Specify whether we may call your endpoint to fetch the shipping rates in the cart. Some webshops offer the possibility to fetch the shipping rates in the cart. Please note that for this request only the zipcode + country of the customer is available.

{"rateEstimate": "true|false"}
DefinitionPOST /external_services.json
Create a new externalService
Example Request
POST /external_services.json
{
	"externalService": {
		"type": "payment",
		"name": "SEOshop Payments",
		"urlEndpoint": "https://api.yourdomain.com/",
		"isActive": true
	}
}
Example Response
HTTP/1.1 201 Created
{
  "externalService": {
    "id": 1,
    "type": "payment",
    "name": "SEOshop Payments",
    "urlEndpoint": "https://api.yourdomain.com/",
    "isActive": true,
    "createdAt": "2015-05-13T10:45:29+02:00",
    "updatedAt": "2015-05-13T10:45:29+02:00"
  }
}

Fetching shipment methods

We will call your endpoint url with a method name like shown below. This is a POST request with a payload that contains the most relevant information from the checkout process.

Arguments

NameValue
checkout_id

The unique identifier for the checkout process

{"checkout_id":1}
customer

Customer object

{
    "customer": {
        "gender": "male|female",
        "birthdate": "Y-m-d",
        "phone": "+31 (0) 20 820 23 91",
        "mobile": "0612345678",
        "national_id": "",
        "email": "info@seoshop.com",
        "password": "",
        "firstname": "Ruud",
        "middlename": "",
        "lastname": "Stelder",
        "type": "private|company",
        "company": "SEOshop Group Bv",
        "vatnumber": "NL10294830B01",
        "cocnumber": "1234567890",
        "sameaddress": true
    }
}
billing_address

Billing address object

{
    "billing_address": {
        "name": "Ruud Stelder",
        "address1": "Keizersgracht",
        "address2": "",
        "number": "313",
        "extension": "",
        "zipcode": "1016 EE",
        "city": "Amsterdam",
        "region": "Noord-Holland",
        "country": "nl"
    }
}
shipping_address

Shipping address object

{
    "shipping_address": {
        "name": "Ruud Stelder",
        "company": "SEOshop Group Bv",
        "address1": "Keizersgracht",
        "address2": "",
        "number": "313",
        "extension": "",
        "zipcode": "1016 EE",
        "city": "Amsterdam",
        "region": "Noord-Holland",
        "country": "nl"
    }
}
quote

Quote information like prices, taxes, and products

{
    "quote": {
        "id": 1,
        "price_incl": 65.84,
        "price_excl": 54.41,
        "additional_cost": true,
        "totals": {
            "sub_total": 54.41,
            "taxes": [
                {
                    "percentage": 0.21,
                    "amount": 11.7772
                }
            ],
            "grand_total": 65.84
        },
        "vat_shifted": false,
        "weight": 220,
        "volume": 400,
        "colli": 4,
        "products": [

        ],
        "created_at": "2015-04-15T12:06:17+02:00",
        "updated_at": "2015-04-15T12:07:11+02:00",
        "additional_cost_price_incl": 2,
        "additional_cost_price_excl": 1.6528
    }
}
DefinitionPOST {your_endpoint}/shipment_methods
Create a new shipmentService
Example Request
POST {your_endpoint}/shipment_methods
{
	"rate_estimate": false,
	"shop": {
		"id": 1,
		"language": "nl",
    "currency": "eur"
	},
	"customer": {
		"firstname": "Menno",
		"middlename": false,
		"lastname": "Wolvers",
		"phone": false,
		"mobile": false,
		"type": "private",
		"company": ""
	},
	"billing_address": {
		"name": "Menno Wolvers",
		"company": "",
		"address1": "Keizersgracht",
		"address2": null,
		"number": 313,
		"extension": "",
		"zipcode": "1016 EE",
		"city": "Amsterdam",
		"region": false,
		"country": "nl"
	},
	"shipping_address": {
		"name": "Menno Wolvers",
		"company": "",
		"address1": "Keizersgracht",
		"address2": null,
		"number": 313,
		"extension": "",
		"zipcode": "1016 EE",
		"city": "Amsterdam",
		"region": false,
		"country": "nl"
	},
	"quote": {
		"id": 1486,
		"price_incl": "36.58",
		"price_excl": "30.23",
		"vat_shifted": false,
		"weight": 110,
		"volume": 200,
		"colli": 2,
		"products": [{
			"product_id": 10546,
			"variant_id": 17706,
			"title": "Lamswollen sjaal",
			"fulltitle": "Lamswollen sjaal",
			"variant": null,
			"description": "Een fijngebreide sjaal van lamswolmix met blokstrepen. Afmeting 35x185 cm.",
			"price_incl": 36.58,
			"price_excl": 30.23,
			"tax_rate": 0.21,
			"quantity": 2,
			"article_code": null,
			"ean": null,
			"sku": "AC0002",
			"size_x": 10,
			"size_y": 10,
			"size_z": 10,
			"weight": 110,
			"volume": 200,
			"colli": 2,
			"stock_available": true
		}]
	}
}
Example Response
HTTP/1.1 201 Created
{
  "shipment_methods": [
    {
      "title": "1 hour delivery",
      "description": "We'll deliver your package within one hour, inside Amsterdam.",
      "price_incl": 6.05,
      "price_excl": 5.00,
      "tax_rate": 0.21,
      "is_pickup": false,
      "is_servicepoint": false,
      "is_cash_on_delivery": false
    }
  ]
}

Rate estimate call

If you have set the field rateEstimate to true, we'll call your service in the cart to fetch the shipment rates. This call is similar to the "Fetch shipment methods" call but with a smaller payload. In the cart we do not have that much information about the customer yet.

Arguments

NameValue
shop

Shop information like the unique identifier, the current language and the active currency

{
    "shop": {
        "id": 1,
        "language": "nl",
        "currency": "eur"
    }
}
shipping_address

The available shipping address data, only the zipcode and country are known for now as we haven't reached the checkout yet

{
    "shipping_address": {
        "zipcode": "1016 EE",
        "country": "nl"
    }
}
quote

Quote information like prices, taxes, and products

{
    "quote": {
        "id": 1,
        "price_incl": 65.84,
        "price_excl": 54.41,
        "additional_cost": true,
        "totals": {
            "sub_total": 54.41,
            "taxes": [
                {
                    "percentage": 0.21,
                    "amount": 11.7772
                }
            ],
            "grand_total": 65.84
        },
        "vat_shifted": false,
        "weight": 220,
        "volume": 400,
        "colli": 4,
        "products": [

        ],
        "created_at": "2015-04-15T12:06:17+02:00",
        "updated_at": "2015-04-15T12:07:11+02:00",
        "additional_cost_price_incl": 2,
        "additional_cost_price_excl": 1.6528
    }
}
DefinitionPOST {your_endpoint}/shipment_methods
Create a new shipmentService/rateEstimate
Example Request
POST {your_endpoint}/shipment_methods
{
	"rate_estimate": true,
	"shop": {
		"id": 1,
		"language": "nl",
    "currency": "eur"
	},
	"shipping_address": {
		"zipcode": "1016 EE",
		"country": "nl"
	},
	"quote": {
		"id": 1486,
		"price_incl": "18.29",
		"price_excl": "15.12",
		"vat_shifted": false,
		"weight": 55,
		"volume": 100,
		"colli": 1,
		"products": [{
			"product_id": 10546,
			"variant_id": 17706,
			"title": "Lamswollen sjaal",
			"fulltitle": "Lamswollen sjaal",
			"variant": null,
			"description": "Een fijngebreide sjaal van lamswolmix met blokstrepen. Afmeting 35x185 cm.",
			"price_incl": 18.29,
			"price_excl": 15.12,
			"tax_rate": 0.21,
			"quantity": 1,
			"article_code": null,
			"ean": null,
			"sku": "AC0002",
			"size_x": 10,
			"size_y": 10,
			"size_z": 10,
			"weight": 55,
			"volume": 100,
			"colli": 1,
			"stock_available": true
		}]
	}
}
Example Response
HTTP/1.1 201 Created
{
	"shipment_methods": [{
		"id": 2,
		"title": "1 hour delivery",
		"description": "We'll drop by in 1 hour and deliver your package!",
		"address": "",
		"price_incl": 6.05,
		"price_excl": 5,
		"tax_rate": 0.21,
		"is_servicepoint": 0,
		"is_cash_on_delivery": 0,
		"is_pickup": 0
	}]
}

Shipment method object

Below you'll find all the available properties with which you can define a shipping method.

Example object
{
  "id": 2,
  "title": "1 hour delivery",
  "description": "We'll drop by in 1 hour and deliver your package!",
  "address": "",
  "price_incl": 6.05,
  "price_excl": 5,
  "tax_rate": 0.21,
  "is_servicepoint": 0,
  "is_cash_on_delivery": 0,
  "is_pickup": 0
}

Properties

NameValue
id

A unique identifier for this shipment method

{"id":1}
title

The name of the shipment method that is shown to the customer

{"title": "DHL"}
description

Explain your carrier service so that consumers actually want to use it

{"description": "The most awesome and fast delivery service"}
price_incl

The price for this shipment method including VAT, that will be added onto the total order value
(format: float)

{"price_incl":6.05}
price_excl

The price for this shipment method excluding VAT, that will be added onto the total order value
(format: float)

{"price_excl":5}
tax_rate

The tax rate for this shipment method, in precentages
(format: float)

{"tax_rate":0.21}
is_pickup

Specifies whether the shipment service is a pickup service, and the customer will have to pick the package up (status = waiting_for_pickup
(format: boolean)

{"is_pickup": "false|true"}
is_servicepoint

Specifies whether the shipment service is related to a service point, where the package has to be picked up (status = shipped)
(format: boolean)

{"is_servicepoint": "false|true"}
is_cash_on_delivery

Specifies whether the shipment service has a cash on delivery, and the customer has to pay when the package is received (status = shipped)
(format: boolean)

{"is_cash_on_delivery": "false|true"}
Was this article helpful? Yes No
One moment please
Thanks for your feedback.