Checkouts

You have to pass through the checkout process to place an order with your product variants.

Create

Attribute

Field	Type	Description	Required
external_reference	string	External reference may be use to specifies where an order originally came from.
external_identifier	string	External identifier may be used to reference an order from another external system. We do not check for uniqueness!
cost_centre	string	Cost centre will be printed on packing slip.
email	string	E-mail. RFC3696/5321 compliant	yes
items	array	Items. An array of Item Objects	yes
shipping_address	object	Shipping address. Address Object	yes
billing_address	object	Billing address. If you do not specify this address, it corresponds to the shipping address. Address Object
whitelabel_address	object	White label / Sender address. Address Object

Item Object

Back to Attributes

Field	Type	Description	Required
variant_id	integer	Id of the product variant	yes
quantity	integer	The quantity to be ordered	yes

Address Object

Back to Attributes

Field	Type	Description	Required
company	string	Company
first_name	string	First name	yes
last_name	string	Last name	yes
street1	string	First street line. Limited to 35 characters	yes
street2	string	Second street line. Limited to 35 characters
zip	string	Zip code	yes
city	string	City	yes
province_code	string	Requires a one or three-digit code. Example: 'AL' (Alabama) or 'QLD' (Queensland)	Only for shipments to the United States, Canada, Australia and Israel.
country_code	ISO 3166-1-alpha-2 code (ISO 2 country code)	Example: 'US' or 'DE'. All accepted values can be found on the Official ISO website.	yes
email	string	Contact person's e-mail address, RFC3696/5321 compliant.	yes
phone	string	So that, for example, the parcel service can call the address/dispatcher of the parcel in case of problems with shipping.	yes
vat_in	string	Sales tax

Example

Request

POST /checkouts HTTP/1.1
{
   "email": "[email protected]",
   "cost_centre": "lorem 1234",
   "items": [
        {
            "variant_id": 1,
            "quantity": 1
        }
   ],
   "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "street1": "123 Main St",
        "zip": "12345",
        "city": "Anytown",
        "country_code": "DE",
        "province_code": "NW",
        "phone": "12345 67890",
        "email": "[email protected]"
   }
}

Response

{
    "id": 1,
    "is_test": true,
    "external_identifier": null,
    "external_reference": null,
    "cost_centre": "lorem 1234",
    "state": "incompleted",
    "customer_locale": "en",
    "currency": "EUR",
    "total": 123.75,
    "subtotal": 103.99,
    "total_tax": 19.76,
    "total_items_price": 123.75,
    "shipping_line": [],
    "created_at": "2017-09-29T09:14:11+00:00",
    "updated_at": "2017-09-29T09:14:11+00:00",
    "cancelled_at": null,
    "items": [
        {
            "id": 75,
            "quantity": 1,
            "total": 123.75,
            "price": 103.99,
            "total_tax": 19.76,
            "tax_rate": 19,
            "variant": {
                "id": 1,
                "total": 123.75,
                "price": 103.99,
                "tax": 19.76,
                "tax_rate": 19,
                "attributes": [
                    {
                        "name": "color",
                        "value": "LightPink"
                    },
                    {
                        "name": "size",
                        "value": "M"
                    }
                ],
                "origin": {
                    "code": "2032095419441"
                },
                "media_id": 81,
                "views": [],
                "state": "finished",
                "created_at": "2017-09-27T10:10:33+00:00",
                "updated_at": "2017-09-27T10:10:34+00:00"
            },
            "created_at": "2017-09-29T09:14:11+00:00",
            "updated_at": "2017-09-29T09:14:11+00:00",
            "cancelled_at": null
        }
    ],
    "customer": {
        "id": 98,
        "first_name": null,
        "last_name": null,
        "email": "[email protected]",
        "phone": null,
        "addresses": [],
        "default_address": null,
        "created_at": "2017-09-29T09:14:11+00:00",
        "updated_at": "2017-09-29T09:14:11+00:00"
    },
    "shipping_address": {
        "id": 190,
        "default": true,
        "company": null,
        "first_name": "John",
        "last_name": "Doe",
        "city": "Anytown",
        "street1": "123 Main St",
        "street2": null,
        "zip": "12345",
        "phone": "12345 67890",
        "email": "[email protected]",
        "province_code": "NW",
        "country_code": "DE",
        "vat_in": null,
        "created_at": "2017-09-29T09:14:11+00:00",
        "updated_at": "2017-09-29T09:14:11+00:00"
    },
    "billing_address": {
        "id": 191,
        "default": true,
        "company": null,
        "first_name": "John",
        "last_name": "Doe",
        "city": "Anytown",
        "street1": "123 Main St",
        "street2": null,
        "zip": "12345",
        "phone": "12345 67890",
        "email": "[email protected]",
        "province_code": "NW",
        "country_code": "DE",
        "vat_in": null,
        "created_at": "2017-09-29T09:14:11+00:00",
        "updated_at": "2017-09-29T09:14:11+00:00"
    },
    "whitelabel_address": null,
    "transactions": [],
    "fulfillments": [],
    "id_tags": []
}

Shipping Rates

To be able to send the order, it is necessary to query the shipping rates and select the appropriate shipping method. This happens asynchronously and you have to use Polling or Webhooks.

If the response is 200 OK, you have to update the shipping_line in the checkout with the desired shipment handle.

Example

Request

GET /checkouts/1/shipping-rates HTTP/1.1

Response

HTTP/1.1 202 Accepted
Location https://api.smake.io/jobs/1

Request as soon as the task is completed.

GET /checkouts/1/shipping-rates HTTP/1.1

Response

{
    "data": [
        {
            "is_test": true,
            "order_id": 1,
            "handle": "pickup",
            "title": "Abholung",
            "price": 22
        }
    ],
    "links": {
        "first": "/?page=1",
        "last": null,
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "/",
        "per_page": 15,
        "to": 1
    }
}

Webhook Payloads always have all shipping rates, so the pagination is not available.

Update

During the process it is possible to update the checkout.

If you change shipping_address afterwards, you have to request the shipping ratess again and update the shipping_line.

Examples

Request to update the items

PUT /checkouts/1 HTTP/1.1

{
    "items": [
        {
            "variant_id": 3,
            "quantity": 1
        },
        {
             "variant_id": 4,
             "quantity": 5
        }
    ]
}

Response

{
    ...
    "items": [
        {
            "id": 77,
            "quantity": 1,
            ...
            "variant": {
                "id": 3,
                ...
            },
        },
        {
            "id": 78,
            "quantity": 5,
            ...
            "variant": {
                "id": 4,
                ...
            },
        }
    ],
    ...
}

Request to update the shipping_line

PUT /checkouts/1 HTTP/1.1

{
    "shipping": {
        "handle": "pickup"
    }
}

Response

{
    ...
    "shipping_line": {
        "title": "Pickup",
        "price": 22.06,
        "total": 26.25,
        "tax": 4.19
    },
    ...
}

Complete

To complete the purchase, the payment.handle must be transferred. The payment.handle parameter accepts all handles that are listed within endpoint payment-methods.

You can then use the orders endpoint to list and filter your orders.

Example

Request to complete a checkout

PUT /checkouts/1/complete HTTP/1.1

{
    "payment": {
      "handle": "invoice",
    }
}

Checkouts

On this page